Upgrading ownCloud with the Updater App

Introduction

The Updater app automates many of the steps of upgrading an ownCloud installation. It is useful for installations that do not have root access, such as shared hosting, for installations with a smaller number of users and data, and it automates manual installations.

When upgrading from oC 9.0 to 9.1 with existing Calendars or Addressbooks please have a look at the release notes of oC 9.0 for important info about this migration.

Downgrading is not supported and risks corrupting your data! If you want to revert to an older ownCloud version, install it from scratch and then restore your data from backup. Before doing this, file a support ticket (if you have paid support) or ask for help in the ownCloud forums to see if your issue can be resolved without downgrading.

We strongly recommend that you make regular backups, as well as a fresh backup before every upgrade.

The Updater app does not backup your database or data directory.

We also recommend that you review any installed third-party apps for compatibility with the new ownCloud release. Ensure that they are all disabled before beginning the upgrade. After the upgrade is complete, re-enable any which are compatible with the new release.

Unsupported apps may disrupt your upgrade.

The Updater app performs these operations:

  • Creates an updater_backup directory under your ownCloud data directory

  • Downloads and extracts updated package content into the updater_backup/packageVersion directory

  • Makes a copy of your current ownCloud instance, except for your data directory, to updater_backup/currentVersion-randomstring

  • Moves all directories except data and config from the current instance to updater_backup/tmp

  • Moves all directories from updater_backup/packageVersion to the current version

  • Copies your old config.php to the new config/ directory

Using the Updater app to update your ownCloud installation is just a few steps:

  1. You should see a notification at the top of any ownCloud page when there is a new update available.

  2. Even though the Updater app backs up important directories, you should always have your own current backups (See Backing up ownCloud for details.)

  3. Verify that the HTTP user on your system can write to your whole ownCloud directory; see the Setting Permissions for Updating section below.

  4. Navigate to Settings  Admin  General and click the Open updater button. This takes you to the Updater control panel.

  5. Click Start, and carefully read the messages. If there are any problems it will tell you. The most common issue is directory permissions; your HTTP user needs write permissions to your whole ownCloud directory. (See Set Correct Permissions.) Another common issue is SELinux rules (see SELinux Configuration.) Otherwise you will see messages about checking your installation and making backups.

  6. Click Proceed, and then it performs the remaining steps, which takes a few minutes.

  7. If your directory permissions are correct, a backup was made, and downloading the new ownCloud archive succeeded you will see the following screen. Click the Start Update button to complete your update:

image

If you have a large ownCloud installation and have shell access, you should use the occ upgrade command, running it as your HTTP user, instead of clicking the Start Update button, in order to avoid PHP timeouts.

This example is for Ubuntu Linux:

sudo -u www-data ./occ upgrade

The optional parameter to skip migration tests during this step was removed in ownCloud 10.0.

  1. It runs for a few minutes, and when it is finished displays a success message, which disappears after a short time.

Refresh your Admin page to verify your new version number. In the Updater section of your Admin page you can see the current status and backups. These are backups of your old and new ownCloud installations, and do not contain your data files. If your update works and there are no problems you can delete the backups from this screen.

If the update fails, then you must update manually.

Setting Permissions for Updating

For hardened security, we highly recommend setting the permissions on your ownCloud directory as strictly as possible, immediately after the initial installation. However, these strict permissions will prevent the Updater app from working, as it needs your whole ownCloud directory to be owned by the HTTP user.

So to set the appropriate permissions for updating, run the code below. Replace the ocpath variable with the path to your ownCloud directory, and replace the htuser and htgroup variables with your HTTP user and group.

#!/bin/bash
# Sets permissions of the owncloud instance for updating

ocpath='/var/www/owncloud'
htuser='www-data'
htgroup='www-data'

chown -R ${htuser}:${htgroup} ${ocpath}

You can find your HTTP user in your HTTP server configuration files. Or you can use PHP Version and Information. Look for the User/Group line.

  • The HTTP user and group in Debian/Ubuntu is www-data.

  • The HTTP user and group in Fedora/CentOS is apache.

  • The HTTP user and group in Arch Linux is http.

  • The HTTP user in openSUSE is wwwrun, and the HTTP group is www.

After the update is completed, re-apply the strong directory permissions immediately.

Command Line Options

The Updater app includes command-line options to automate updates, to create checkpoints and to roll back to older checkpoints. You must run it as your HTTP user. This example on Ubuntu Linux displays command options:

sudo -u www-data ./occ updater/application.php list

See usage for commands, like this example for the upgrade:checkpoint command:

sudo -u www-data ./occ updater/application.php upgrade:checkpoint -h

You can display a help summary:

sudo -u www-data ./occ updater/application.php --help

When you run it without options it runs a system check:

sudo -u www-data ./occ owncloud/updater/application.php
ownCloud updater 1.0 - CLI based ownCloud server upgrades
Checking system health.
- file permissions are ok.
Current version is 9.0.0.12
No updates found online.
Done

Create a checkpoint:

sudo -u www-data ./occ updater/application.php upgrade:checkpoint --create
Created checkpoint 9.0.0.12-56d5e4e004964

List checkpoints:

sudo -u www-data ./occ updater/application.php upgrade:checkpoint --list

Restore an earlier checkpoint:

sudo -u www-data ./occ updater/application.php \
    upgrade:checkpoint --restore=9.0.0.12-56d5e4e004964

Add a line like this to your crontab to automatically create daily checkpoints:

2 15 * * * sudo -u www-data ./occ /path/to/owncloud/updater/application.php upgrade:checkpoint --create > /dev/null 2>&1

updater.secret value in config.php

When running the updater, you will be prompted to add a hashed secret into your config.php file. On the updater web interface, you then need to enter the unhashed secret into the web form.

In case you forgot your password/secret, you can re-create it by changing config.php. You can run this on your shell:

php -r 'echo password_hash("Enter a random password here", PASSWORD_DEFAULT)."\n";'

Please replace Enter a random password here with your own. Then add this into your config.php:

'updater.secret' => 'The value you got from the above hash command',