Maintenance

Monitoring

OpenMetrics

New in version 33

Nextcloud exposes a /metrics endpoint. By default, it responds only on localhost. You can change this behaviour with openmetrics_allowed_clients

'openmetrics_allowed_clients' => [
  '192.168.0.0/16',
],

注意

Ensure this endpoint is not accessible to everyone as it could lead to some load on your server.

You can view the content of this endpoint with the following command:

curl "https://your.domain/metrics"

If for some reason you want to disable some metrics (eg. if they take too long to generate), you can disable them by adding their class name into openmetrics_skipped_classes

'openmetrics_skipped_classes' => [
  'OC\OpenMetrics\Exporters\FilesByType',
],

另见

Check Configuration Parameters for more information

Maintenance

Backup

To backup a Nextcloud installation there are five main things you need to retain:

  1. The config folder
  2. The custom apps folder (only if you have custom apps installed)
  3. The data folder
  4. The theme folder
  5. The database

Maintenance mode

maintenance:mode locks the sessions of logged-in users and prevents new logins in order to prevent inconsistencies of your data. You must run occ as the HTTP user, like this example on Ubuntu Linux:

$ sudo -E -u www-data php occ maintenance:mode --on

You may also put your server into this mode by editing config/config.php. Change "maintenance" => false to "maintenance" => true:

<?php

 "maintenance" => true,

Don't forget to change it back to false when you are finished.

Backup folders

Copy your config, data, and theme directories to a location outside your Nextcloud environment. Alternatively, copy your entire Nextcloud installation directory (including the data directory). You could use this command:

rsync -Aavx nextcloud/ nextcloud-dirbkp_`date +"%Y%m%d"`/

Backup database

注意

Before restoring a backup see Restoring backup

MariaDB

MariaDB is the recommended database engine. To backup MariaDB using mariadb-dump:

mariadb-dump --single-transaction -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

If you have enabled MariaDB 4-byte support (Enabling MySQL 4-byte support, needed for emoji), add --default-character-set=utf8mb4:

mariadb-dump --single-transaction --default-character-set=utf8mb4 -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

MySQL

To backup MySQL:

mysqldump --single-transaction -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

If you have enabled MySQL 4-byte support (Enabling MySQL 4-byte support, needed for emoji), add --default-character-set=utf8mb4:

mysqldump --single-transaction --default-character-set=utf8mb4 -h [server] -u [username] -p[password] [db_name] > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

SQLite

sqlite3 data/owncloud.db .dump > nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

PostgreSQL

PGPASSWORD="password" pg_dump [db_name] -h [server] -U [username] -f nextcloud-sqlbkp_`date +"%Y%m%d"`.bak

Restoring backup

To restore a Nextcloud installation there are four main things you need to restore:

  1. The configuration directory
  2. The data directory
  3. The database
  4. The theme directory

提示

You must have the database, data directory, and configuration files. You cannot complete restoration without all three.

Restore folders

提示

This guide assumes that your previous backup is called "nextcloud-dirbkp"

Simply copy your configuration and data folder (or even your whole Nextcloud install and data folder) to your Nextcloud environment. You could use this command:

rsync -Aax nextcloud-dirbkp/ nextcloud/

Restore database

注意

Before restoring a backup you need to make sure to delete all existing database tables.

The easiest way to do this is to drop and recreate the database. SQLite does this automatically.

MariaDB

MariaDB is the recommended database engine. To restore MariaDB using the mariadb client:

mariadb -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mariadb -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud"

If you use UTF8 with multibyte support (e.g. for emojis in filenames), use:

mariadb -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mariadb -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci"

MySQL

To restore MySQL:

mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud"

If you use UTF8 with multibyte support (e.g. for emojis in filenames), use:

mysql -h [server] -u [username] -p[password] -e "DROP DATABASE nextcloud"
mysql -h [server] -u [username] -p[password] -e "CREATE DATABASE nextcloud CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci"

PostgreSQL

PGPASSWORD="password" psql -h [server] -U [username] -d template1 -c "DROP DATABASE \"nextcloud\";"
PGPASSWORD="password" psql -h [server] -U [username] -d template1 -c "CREATE DATABASE \"nextcloud\";"

Restoring

提示

This guide assumes that your previous backup is called "nextcloud-sqlbkp.bak"

MariaDB

MariaDB is the recommended database engine. To restore MariaDB using the mariadb client:

mariadb -h [server] -u [username] -p[password] [db_name] < nextcloud-sqlbkp.bak

MySQL

To restore MySQL:

mysql -h [server] -u [username] -p[password] [db_name] < nextcloud-sqlbkp.bak

SQLite

rm data/owncloud.db
sqlite3 data/owncloud.db < nextcloud-sqlbkp.bak

PostgreSQL

PGPASSWORD="password" psql -h [server] -U [username] -d nextcloud -f nextcloud-sqlbkp.bak

Synchronising with clients after data recovery

By default the Nextcloud server is considered the authoritative source for the data. If the data on the server and the client differs clients will default to fetching the data from the server.

If the recovered backup is outdated the state of the clients may be more up to date than the state of the server. In this case also make sure to run the maintenance:data-fingerprint command afterwards. It changes the logic of the synchronisation algorithm to try and recover as much data as possible. Files missing on the server are therefore recovered from the clients and in case of different content the users will be asked.

This can also help in rare scenarios when the database is newer than the data directory. The server will restore the data from the clients and preserve the shares. Until then the files would be visible but not accessible. A files:scan is required afterwards to update the database.

提示

The usage of maintenance:data-fingerprint can cause conflict dialogues and difficulties deleting files on the client. Therefore it's only recommended to prevent dataloss if the backup was outdated. This command does not require the server to be in maintenance mode.

If you are running multiple application servers you will need to make sure the config files are synced between them so that the updated data-fingerprint is applied on all instances.

How to upgrade

Overview

The approach used to upgrade your Nextcloud Server depends on your installation type. This manual mainly focuses on the methods that apply to an Archive based installation. If you installed using Snap, Docker, a pre-built VM, or a package management tool then refer to the installation and update instructions for that installation method for the most accurate upgrading instructions (generally located at the distribution point for the install method you chose).

There are two ways to upgrade an Archive based Nextcloud Server deployment:

The Built-in Updater, in either Web or command-line mode, is the easiest choice for most environments. However some environments require the manual approach. Both approaches are covered fully here.

说明

Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review critical changes first. These are highlights of changes that may be required in your environment to accommodate changes in Nextcloud Server. These notes are periodically revised as needed so it is also a good idea to revisit them periodically, such as when proceeding with maintenance upgrades.

When an update is available for your Nextcloud server, by default you will receive a notification. You can also check for available updates by visiting the Update section under Administration settings->Overview in the Web UI.

提示

It is best to keep your Nextcloud server upgraded regularly. This means installing all maintenance/point releases and upgrading to new major releases before your current one reaches end-of-life status. Examples of major releases are 27, 28, or 29. Maintenance releases are intermediate releases for each major release that address critical functionality or security bugs. For example 28.0.4 and 29.0.2 are maintenance releases.

Approaching Upgrades

Nextcloud must be upgraded step by step:

Wait for background migrations to finish after major upgrades. After upgrading to a new major version, some migrations are scheduled to run as a background job. If you plan to upgrade directly to another major version (e.g. 24 -> 25 -> 26) you need to make sure these migrations were executed before starting the next upgrade. To do so you should run the cron.php file 2-3 times, for example:

$ sudo -E -u www-data php -f /var/www/nextcloud/cron.php

For more information about background jobs see Background jobs.

Upgrading is disruptive. Your Nextcloud server will be put into maintenance mode, so your users will be locked out until the upgrade is completed. Large installations may take several hours to complete the upgrade. Nevertheless usual upgrade times even for bigger installations are in the range of a few minutes.

注意

Downgrading is not supported and risks corrupting your data! If you want to revert to an older Nextcloud version, make a new, fresh installation 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 Nextcloud forums to see if your issue can be resolved without downgrading.

Update notifications

Nextcloud has an update notification app, that informs the administrator about the availability of an update. Then you decide which update method to use.

Both update notifications displayed on Admin page.

Figure 1: The top banner is the update notification that is shown on every page, and the Updates section can be found in the admin page

From there the web based updater can be used to fetch this new code. There is also an CLI based updater available, that does exactly the same as the web based updater but on the command line.

Prerequisites

另见

If you upgrade from a previous major version please see critical changes first.

You should always maintain regular backups and make a fresh backup before every upgrade.

Then review third-party apps, if you have any, for compatibility with the new Nextcloud release. Any apps that are not developed by Nextcloud show a 3rd party designation. Install unsupported apps at your own risk. Then, before the upgrade, all 3rd party apps must be disabled. After the upgrade is complete you may re-enable them.

Maintenance mode

You can put your Nextcloud server into maintenance mode before performing upgrades, or for performing troubleshooting or maintenance. Please see Using the occ command to learn how to put your server into the maintenance mode (maintenance:mode) or execute repair commands (maintenance:repair) with the occ command.

The built-in Updater does this for you before replacing the existing Nextcloud code with the code of the new Nextcloud version.

maintenance:mode locks the sessions of logged-in users and prevents new logins. This is the mode to use for upgrades. You must run occ as the HTTP user, like this example on Ubuntu Linux:

$ sudo -E -u www-data php occ maintenance:mode --on

You may also put your server into this mode by editing config/config.php. Change "maintenance" => false to "maintenance" => true:

<?php

 "maintenance" => true,

Then change it back to false when you are finished.

Manual steps during upgrade

Some operation can be quite time consuming. Therefore we decided not to add them to the normal upgrade process. We recommend to run them manually after the upgrade was completed. Below you find a list of this commands.

Long running migration steps

From time to time we do some changes to the database layout that take a lot of time, but can be executed while Nextcloud stays online. Thus we moved them into a separate command that an administrator can execute on the CLI without the need to lock the instance into maintenance mode (at least for some of them). The instance will also work without those changes applied, but performance is improved significantly by them. There is also always an hint in the setup checks of the admin settings web interface.

Those include for example:

$ sudo -E -u www-data php occ db:add-missing-columns
$ sudo -E -u www-data php occ db:add-missing-indices
$ sudo -E -u www-data php occ db:add-missing-primary-keys

You can use the --dry-run option to output the SQL queries instead of executing them.

Upgrade via built-in updater

The built-in updater automates many of the steps of upgrading a Nextcloud 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 updating manual installations.

注意

Downgrading is not supported and risks corrupting your data! If you want to revert to an older Nextcloud 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 Nextcloud forums to see if your issue can be resolved without downgrading.

警告

You should maintain regular backups (see Backup), and make a backup before every update. The built-in updater does not backup your database or data directory.

What does the updater do?

提示

The built-in updater itself only replaces the existing files with the ones from the version it updates to. The migration phase, which upgrades your database and apps, needs to be executed afterwards. In command line mode, the updater offers to trigger this for you right after the code was successfully replaced by running occ upgrade for you. In web mode, the updater finishes and then offers to send you back to your instance's main URL to trigger the migration phase's web UI.

The built-in updater performs these operations:

Using the command line based updater

  1. You should see a notification at the top of any Nextcloud page when there is a new update available. Go to the admin settings page and scroll to the section "Version". This section has a button to open the updater. This section as well as the update notification is only available if the update notification app is enabled in the apps management.

Nextcloud admin settings Version section showing an update available notification

  1. Instead of clicking that button you can now invoke the command line based updater by going into the updater/ directory in the Nextcloud directory and executing the updater.phar as the web server user. (i.e. sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar)

Terminal showing Nextcloud command line updater starting and displaying update information

  1. Verify the information that is shown and enter "Y" to start the update.

Terminal showing Nextcloud command line updater executing update steps

Terminal showing Nextcloud command line updater with a failed step and error feedback

  1. In case an error happens or the check failed the updater stops processing and gives feedback. You can now try to solve the problem and re-run the updater command. This will continue the update and re-run the failed step. It will not re-run the previous succeeded steps.

Terminal showing Nextcloud command line updater ready to continue after resolving an error

  1. Once all steps are executed the updater will ask you a final question: "Should the "occ upgrade" command be executed?". This allows you to directly execute the command line based upgrade procedure (occ upgrade). If you select "No" then it will finish with Please now execute "./occ upgrade" to finish the upgrade..

Terminal showing Nextcloud command line updater asking whether to run the occ upgrade command

  1. Once the occ upgrade is done you get asked if the maintenance mode should be kept active.

Terminal showing Nextcloud command line updater asking whether to keep maintenance mode active

Batch mode for command line based updater

It is possible to run the command line based updater in a non-interactive mode. The updater then doesn't ask any interactive questions. It is assumed that if an update is available it should be installed and the occ upgrade command is executed as well. After finishing the maintenance mode will be turned off except an error occurred during the occ upgrade or the replacement of the code.

To execute this, run the command with the --no-interaction option. (i.e. sudo -E -u www-data php /var/www/nextcloud/updater/updater.phar --no-interaction)

Terminal showing Nextcloud command line updater running in non-interactive batch mode

Using a custom download URL

The --url option lets you override the archive the updater downloads. Common use cases:

注意

The normal update rules still apply when using --url:

Passing --url does not bypass these constraints.

Point the updater at any HTTP/HTTPS URL:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url https://download.nextcloud.com/server/releases/nextcloud-33.0.0.zip

New in version 34

For a locally staged archive, use a file:// URL:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip

Signature verification

When --url is used the updater cannot look up the official signature automatically. You have two options:

These options can be combined with --no-interaction for fully automated runs:

sudo -u www-data php /var/www/nextcloud/updater/updater.phar \
    --url file:///tmp/nextcloud-33.0.0.zip \
    --signature "BASE64_SIGNATURE_HERE" \
    --no-interaction

Using the web based updater

The web based updater performs the same steps and checks as the command line based updater.

Using the built-in updater to update your Nextcloud installation is just a few steps:

  1. You should see a notification at the top of any Nextcloud page when there is a new update available. Go to the admin settings page and scroll to the section "Version". This section has a button to open the updater. This section as well as the update notification is only available if the update notification app is enabled in the apps management.

  1. Click the button "Open updater".

  1. Verify the information that is shown and click the button "Start update" to start the update.

  1. In case an error happens or the check failed the updater stops processing and gives feedback. You can now try to solve the problem and click the "Retry update" button. This will continue the update and re-run the failed step. It will not re-run the previous succeeded steps.

  1. In case you close the updater, before it finished you can just open the updater page again and proceed at the last succeeded step. Closing the web page will still execute the running step but will not continue with the next one, because this is triggered by the open updater page.

  1. Once all steps are executed the updater will ask you a final question: "Keep maintenance mode active?". This allows you to use either the web based upgrade page or the command line based upgrade procedure (occ upgrade). Command line access is required if the maintenance mode is kept active.

  1. Done. You now can continue either to the web based upgrade page or run occ upgrade. The two examples "Web based upgrade" and "Command line based upgrade" shows how the screens then look like.

Web based upgrade

This is how the web based update would continue:

Nextcloud web updater showing option to disable maintenance mode after upgrade

Nextcloud upgrade page displayed after the web updater completes

Command line based upgrade

This is how the command line based update would continue:

Nextcloud command line updater asking whether to keep maintenance mode active

$ sudo -u www-data php ./occ upgrade
Nextcloud or one of the apps require upgrade - only a limited number of commands are available
You may use your browser or the occ upgrade command to do the upgrade
Set log level to debug
Updating database schema
Updated database
Updating <files_pdfviewer> ...
Updated <files_pdfviewer> to 1.1.1
Updating <gallery> ...
Updated <gallery> to 17.0.0
Updating <activity> ...
Updated <activity> to 2.5.2
Updating <comments> ...
Updated <comments> to 1.2.0
Updating <theming> ...
Updated <theming> to 1.3.0
Starting code integrity check...
Finished code integrity check
Update successful
Maintenance mode is kept active
Reset log level

Troubleshooting

Upgrade manually

Overview

In some environments using the Built-in Updater in Web mode is not reliable (such as due to web server timeouts) and running it in command-line mode is not an option (such as in some shared hosting environments). In these cases a manual upgrade may be the best approach.

A manual upgrade consists of downloading and unpacking the Nextcloud Archive file either to your PC or host. Then deleting your existing Nextcloud Server installation files and folders, except data/ and config/, on your host. Then moving the new Nextcloud Server installation files into the appropriate place on your host, again preserving your existing data/ and config/ files. And doing a few other housekeeping items, such as making sure your installed apps are transferred into the new installation and adjusting permissions. That may sound like a lot, but detailed instructions are below.

说明

Before upgrading, especially between major versions (e.g. v27.y.z -> v28.y.z) please review critical changes first. These are highlights of changes that may be required in your environment to accommodate changes in Nextcloud Server. These notes are periodically revised as needed so it is a good idea to revisit them even when proceeding with minor and maintenance upgrades just in case.

注意

When upgrading manually, you must confirm your system meets the System requirements of the new version as well as that you are following the standard upgrade requirements (such as upgrading to the latest maintenance release before upgrading to a new major release).

Step-by-Step Manual Upgrade

说明

Always start by making a fresh backup and disabling all 3rd party apps.

  1. Back up your existing Nextcloud Server database, data directory, and config.php file. (See Backup, for restore information see Restoring backup)

  2. Choose a target Nextcloud Server release from https://nextcloud.com/changelog/ and download the Archive file (tarball or zip archive) into an empty directory outside of your current installation.

    注意

    You cannot jump more than one major version forward at a time (i.e. 27->28 is okay, but 27->29 is not).

  3. Unpack the the downloaded tarball or zip archive - e.g.:

    unzip nextcloud-[version].zip
(or)
tar -xjf nextcloud-[version].tar.bz2

  4. Stop your Web server.

  5. In case you are running a cron-job for nextcloud's house-keeping disable it by commenting the entry in the crontab file:

    crontab -u www-data -e

    (Put a # at the beginning of the corresponding line.)

  6. Rename your current Nextcloud directory, for example nextcloud-old.

  7. Unpacking the new archive creates a new nextcloud directory populated with your new server files. Move this directory and its contents to the original location of your old server. For example /var/www/, so that once again you have /var/www/nextcloud.

  8. Copy the config/config.php file from your old Nextcloud directory to your new Nextcloud directory.

  9. If you keep your data/ directory in your nextcloud/ directory, move it from your old version of Nextcloud to your new nextcloud/. If you keep it outside of nextcloud/ then you don't have to do anything with it, because its location is configured in your original config.php, and none of the upgrade steps touch it.

  10. If you are using 3rd party application, it may not always be available in your upgraded/new Nextcloud instance. To check this, compare a list of the apps in the new nextcloud/apps/ folder to a list of the of the apps in your backed-up/old nextcloud/apps/ folder. If you find 3rd party apps in the old folder that needs to be in the new/upgraded instance, simply copy them over and ensure the permissions are set up as shown below.

  11. If you have additional apps folders like for example nextcloud/apps-extras or nextcloud/apps-external, make sure to also transfer/keep these in the upgraded folder.

  12. If you are using 3rd party theme make sure to copy it from your themes/ directory to your new one. It is possible you will have to make some modifications to it after the upgrade.

  13. Adjust file ownership and permissions:

    chown -R www-data:www-data nextcloud
find nextcloud/ -type d -exec chmod 750 {} \;
find nextcloud/ -type f -exec chmod 640 {} \;

  14. Restart your Web server.

  15. Now launch the upgrade from the command line using occ, like this example on Ubuntu Linux:

    sudo -E -u www-data php occ upgrade

    (!) this MUST be executed from within your nextcloud installation directory

  16. The upgrade operation takes a few minutes to a few hours, depending on the size of your installation. When it is finished you will see a success message, or an error message that will tell where it went wrong.

  17. Re-enable the nextcloud cron-job. (See step 4 above.)

    crontab -u www-data -e

    (Delete the # at the beginning of the corresponding line in the crontab file.)

Login and take a look at the bottom of your Admin page to verify the version number. Check your other settings to make sure they're correct. Go to the Apps page and review the core apps to make sure the right ones are enabled. Re-enable your third-party apps.

Previous Nextcloud releases

You'll find previous Nextcloud releases in the Nextcloud Server Changelog.

Troubleshooting

Occasionally, files do not show up after an upgrade. A rescan of the files can help:

sudo -E -u www-data php console.php files:scan --all

See the nextcloud.com support page for further resources.

Sometimes, Nextcloud can get stuck in a upgrade if the web based upgrade process is used. This is usually due to the process taking too long and encountering a PHP time-out. Stop the upgrade process this way:

sudo -E -u www-data php occ maintenance:mode --off

Then start the manual process:

sudo -E -u www-data php occ upgrade

If this does not work properly, try the repair function:

sudo -E -u www-data php occ maintenance:repair

Upgrade via snap packages

Upgrade quickstart

Nextcloud snap is an unofficial Nextcloud designed to be easy to install and simple to maintain. The ideal Nextcloud snap is an "install and forget" Nextcloud instance that works on most architectures and updates itself without needing administrative skills. Combining Nextcloud with snapd makes it a perfect fit for IoT or scalable environments. Snapd is a secure and robust technology which the Nextcloud snap team has embraced.

However, the snap is opinionated.

Installation

On Ubuntu

All other distros be warned

By default the latest stable Nextcloud snap release will be installed and it will automatically update to subsequent stable releases, but there are other releases available as well and you have full control of automatic updates.

After installation, Nextcloud will start automatically. Assuming you and the device on which it was installed are on the same network, you will reach the Nextcloud installation by visiting <hostname>.local or the IP address of the instance in your browser. If your hostname is localhost or localhost.localdomain, like on an Ubuntu Core device, nextcloud.local will be used instead.

1st login

Upon visiting the Nextcloud installation for the first time, you will be prompted to enter an admin username and password before Nextcloud is initialised. This may take a while depending on resources and the device. After you provide that information you will be logged in and able to install apps, create users, and upload files.

Upgrade tips

By default the Nextcloud snap will automatically update to subsequent stable releases. You may however upgrade manually too by issuing the command:

sudo snap refresh nextcloud

If the upgrade fails you can easily revert to the last working version by issuing the command:

sudo snap revert nextcloud

Further documentation, an extensive Wiki and FAQ's can be found on the developers GitHub.

Migrating to a different server

If the need arises Nextcloud can be migrated to a different server. A typical use case would be a hardware change or a migration from the virtual Appliance to a physical server. All migrations have to be performed with Nextcloud offline and no accesses being made. Online migration is supported by Nextcloud only when implementing industry standard clustering and HA solutions before Nextcloud is installed for the first time.

To start let us be specific about the use case. A configured Nextcloud instance runs reliably on one machine. For some reason (e.g. more powerful machine is available but a move to a clustered environment not yet needed) the instance needs to be moved to a new machine. Depending on the size of the Nextcloud instance the migration might take several hours. As a prerequisite it is assumed that the end users reach the Nextcloud instance via a virtual hostname (a CNAME record in DNS) which can be pointed at the new location. It is also assumed that the authentication method (e.g. LDAP) remains the same after the migration.

注意

At NO TIME any changes to the ORIGINAL system are required EXCEPT putting Nextcloud into maintenance mode.

This ensures, should anything unforeseen happen you can go back to your existing installation and provide your users with a running Nextcloud while debugging the problem.

  1. Set up the new machine with the desired OS, install and configure the Web server as well as PHP for Nextcloud (e.g. permissions or file upload size limits) and make sure the PHP version matches Nextcloud supported configuration and all relevant PHP extensions are installed. Also set up the database and make sure it is a Nextcloud supported configuration. If your original machine was installed recently just copying that base configuration is a safe best practice.

    说明

    Before beginning the migration, check the ``config/config.php`` file on your ORIGINAL system to identify any optional services that are configured, such as:

    • Redis or Memcached (for caching/sessions)
    • External object storage (S3, etc.)
    • LDAP
    • Mail server settings
    • Full-text search backends (Elasticsearch, etc.)

    You must also install and configure these same services on the NEW machine before copying the Nextcloud files. Failure to do so may cause errors such as "Redis server went away" or connection failures during Nextcloud startup.

  2. On the original machine then stop Nextcloud. First activate the maintenance mode. After waiting for 6-7 minutes for all sync clients to register the server is in maintenance mode stop the application and/or Web server that serves Nextcloud.

  3. Create a dump from the database and copy it to the new machine. There import it in the database (See Backup and Restoring backup).

  4. Copy all files from your Nextcloud instance, the Nextcloud program files, the data files, the log files and the configuration files, to the new machine (See Backup and Restoring backup). The data files should keep their original timestamp (can be done by using rsync with -t option) otherwise the clients will re-download all the files after the migration. Depending on the original installation method and the OS the files are located in different locations. On the new system make sure to pick the appropriate locations. If you change any paths, make sure to adapt the paths in the Nextcloud config.php file.

    提示

    This step might take several hours, depending on your installation.

    注意

    Changing the location of the data directory might cause a corruption of relations in the database and is not supported.

    说明

    After copying config/config.php to the new machine, review and update every server-specific value before starting Nextcloud. At minimum check:

    • datadirectory — keep this path identical to the original server wherever possible. Changing the data directory path requires a database update and is strongly discouraged; see Troubleshooting data-directory if you have no choice.
    • dbhost, dbname, dbuser, dbpassword — update if the new server uses a different database host or credentials.
    • trusted_domains — add or replace the new server's hostname or IP address.
    • overwrite.cli.url, overwritehost, overwriteprotocol, overwritewebroot — update to reflect the new server's URL and any reverse-proxy setup.
    • memcache.local, memcache.distributed, memcache.locking and the associated connection parameters — update if the cache/session backend address changed on the new machine. Depending on the backend in use, check redis or redis.cluster (for Redis / Redis Cluster) or memcached_servers (for Memcached).
    • objectstore — if external object storage (S3, Swift, etc.) is configured, verify that the endpoint, bucket, and credentials are still valid and reachable from the new server.
    • mail_smtphost, mail_smtpport — update if the SMTP relay differs on the new server.
    • logfile — update if the log path differs on the new server.
    • tempdirectory — if set to a custom path, make sure that path exists and is writable on the new server.
    • serverid — if set, keep the same value. It identifies the server in multi-PHP-server setups and must not change. If you override it per server via the NC_serverid environment variable, configure the same override on the new server.

    The secret and instanceid values are generated once at install time and tied to all encrypted data and user sessions. Do not change or regenerate them. They must be copied verbatim from the original config.php.

    Leaving stale values (especially database credentials or datadirectory) will cause startup errors or data corruption.

  5. Check the config.php file of the ORIGINAL system to see if it has the data-fingerprint set to a non-empty value. If this is the case, make sure to also run the maintenance:data-fingerprint command on the NEW system, similarly to how it is required when performing a backup restoration (See Restoring backup for details).

  6. While still having Nextcloud in maintenance mode (confirm!) and BEFORE changing the CNAME record in the DNS start up the database, Web server / application server on the new machine and point your web browser to the migrated Nextcloud instance. Confirm that you see the maintenance mode notice, that a logfile entry is written by both the Web server and Nextcloud and that no error messages occur. Then take Nextcloud out of maintenance mode and repeat. Log in as admin and confirm normal function of Nextcloud.

  7. Change the CNAME entry in the DNS to point your users to the new location.

Migrating from ownCloud

提示

Especially when migrating from ownCloud to Nextcloud you should create a backup of the config, database and the data directory, in case something goes wrong.

Currently migrating from ownCloud is like performing a manual update. So it is quite easy, to migrate from one ownCloud version to at least one Nextcloud version. However this does only work with versions that are sufficiently compatible in database schema and codebase. See the table below for a version map, where migrating is easily possible:

ownCloud Nextcloud
10.13.x 10.14.x 10.15.x 10.16.x 34.0.0 34.0.0 34.0.0 34.0.0

提示

Since ownCloud does not and will not support PHP 8.0 or higher, you need to upgrade your PHP instance first, after which, ownCloud won't be accessible anymore. See System requirements about PHP versions supported by Nextcloud. We urge you to migrate to Nextcloud since PHP versions prior PHP 8 are end of life, see https://www.php.net/supported-versions.php.

  1. First download the correct version of Nextcloud from our releases page,
  2. Make sure to have do a backup before migrating.
  3. Upgrade PHP to a version supported by the downloaded Nextcloud version.
  4. Follow the upgrade instructions described in the Upgrade manually manual.
  5. Run the following commands after occ upgrade:
  1. If system cron was used, please verify if crontab entry was using the command occ system:cron. If yes, please adjust it to use the php command instead according to the background jobs configuration documentation
  2. In case, use the Nextcloud built-in updater to update your instance to the newest version. This must be done for every major version, since updates between multiple major versions are not supported.
  3. If multiple major version upgrades are done, it might be needed to upgrade PHP again in between.
  4. Make sure to also verify the "Security & setup warnings" in the "Overview" section on the settings page.
  5. In some cases, apps installed from the ownCloud Market might have been disabled as incompatible (ex: calendar and contacts), so you should reinstall the Nextcloud ones using occ app:enable calendar, occ app:enable contacts, etc

Issues and troubleshooting

General troubleshooting

If you have trouble installing, configuring or maintaining Nextcloud, please refer to our community support channels:

Please understand that all these channels essentially consist of users like you helping each other out. Consider helping others out where you can, to contribute back for the help you get. This is the only way to keep a community like Nextcloud healthy and sustainable!

If you are using Nextcloud in a business or otherwise large scale deployment, note that Nextcloud GmbH offers commercial support options.

Bugs

If you think you have found a bug in Nextcloud, please:

If you can't find a solution, please use our bugtracker. You can generate a configuration report with the occ config command, with passwords automatically obscured.

General troubleshooting

Check the Nextcloud System requirements, especially supported browser versions.

When you see warnings about code integrity, refer to Code signing.

Disable 3rdparty / non-shipped apps

It might be possible that 3rd party / non-shipped apps are causing various different issues. Always disable 3rd party apps before upgrades, and for troubleshooting. Please refer to the Apps commands on how to disable an app from command line.

Internal Server Errors

An Internal Server Error, sometimes called a "500 error", indicates that the web server encountered an unexpected condition that prevented it from fulfilling the request.

This error response is a generic "catch-all" response. To find out the source of the error you will need to check your Nextcloud log (located in data/nextcloud.log by default) and possibly your web server's error log (depending on where the failure is occurring).

提示

Whenever possible, Nextcloud will include the "Request id" in the error. This request ID can be searched for in your Nextcloud log file to find entries associated with the failing transaction.

Nextcloud log files

The Nextcloud log file is located in the data directory by default - e.g. data/nextcloud.log. If the Web UI is still reachable, it is also available via Administration settings->Logging.

提示

When asking for help, the entire raw log entry is generally required.

For some situations you may need to adjust the log level in your config.php file. Please see Logging for more information on these log levels.

Some logging - for example JavaScript console logging - needs debugging enabled. Edit config/config.php and change 'debug' => false, to 'debug' => true, Be sure to change it back when you are finished.

For JavaScript issues you will also need to view the javascript console. All major browsers have developer tools for viewing the console, and you usually access them by pressing F12.

PHP version and information

You will need to know the PHP version and configuration that is in-use on your Nextcloud server. This will not necessarily be the same version and configuration as can be reached from the command-line. The simplest way to gather this information is by using what's commonly referenced as phpinfo().

The most accurate - and easiest - way to access phpinfo is by checking it from within Nextcloud itself. Of course, this requires that Nextcloud is functioning enough that you can log in as an administrator and access the Administration settings -> System menu. If so, you can enable the exposure of phpinfo data by toggling it on via occ:

./occ config:app:set --value=yes serverinfo phpinfo

From then on a new button labeled Show phpinfo will be visible in the web interface under Administration settings -> System. Clicking it will expose just about everything you may want to know about your PHP environment.

If accessing the Nextcloud web interface is not an option, you may create a plain-text file named phpinfo.php and place it in your Web root, for example /var/www/html/phpinfo.php. (Your Web root may be in a different location; your Linux distribution documentation will tell you where.) This file contains just this line:

<?php phpinfo(); ?>

Open this file in a Web browser by pointing your browser to localhost/phpinfo.php:

Your PHP version is at the top, and the rest of the page contains abundant system information such as active modules, active .ini files, and much more. When you are finished reviewing your information you must delete phpinfo.php, or move it outside of your Web directory, because it is a security risk to expose such sensitive data.

Debugging sync issues

注意

The data directory on the server is exclusive to Nextcloud and must not be modified manually.

Disregarding this can lead to unwanted behaviors like:

If you need to directly upload files from the same server please use a WebDAV command line client like cadaver to upload files to the WebDAV interface at:

https://example.com/nextcloud/remote.php/dav

Common problems / error messages

Some common problems / error messages found in your logfiles as described above:

Troubleshooting Web server and PHP problems

Logfiles

When having issues the first step is to check the logfiles provided by PHP, the Web server and Nextcloud itself.

提示

In the following the paths to the logfiles of a default Debian installation running Apache2 with mod_php is assumed. On other Web servers, Linux distros or operating systems they can differ.

Web server and PHP modules

提示

Lighttpd is not supported with Nextcloud, and some Nextcloud features may not work at all on Lighttpd.

There are some Web server or PHP modules which are known to cause various problems like broken uploads/downloads. The following shows a draft overview of these modules:

  1. Apache
  1. NginX
  1. PHP

Troubleshooting WebDAV

Nextcloud uses SabreDAV, and the SabreDAV documentation is comprehensive and helpful.

See:

There is also a well maintained FAQ thread available at the ownCloud Forums which contains various additional information about WebDAV problems.

Service discovery

Some clients - especially on iOS/macOS - have problems finding the proper sync URL, even when explicitly configured to use it.

If you want to use CalDAV or CardDAV clients or other clients that require service discovery together with Nextcloud it is important to have a correct working setup of the following URLs:

https://example.com/.well-known/carddav
https://example.com/.well-known/caldav

Those need to be redirecting your clients to the correct endpoints. If Nextcloud is running at the DocumentRoot of your Web server the correct URL is https://example.com/remote.php/dav for CardDAV and CalDAV and if running in a subfolder like nextcloud, then the correct URL is https://example.com/nextcloud/remote.php/dav.

提示

On Debian/Ubuntu systems, the Apache DocumentRoot defaults to /var/www/html. On other distributions, this path may differ. Adjust paths in the examples below accordingly.

For the first case, the .htaccess file shipped with Nextcloud should do this work for you when you're running Apache. You need to make sure that your Web server is using this file. Additionally, you need the mod_rewrite Apache module installed and AllowOverride All set in your apache2.conf or vHost-file to process these redirects. When running Nginx please refer to NGINX configuration.

For the second case, you need to add the following to /etc/apache2/apache2.conf, replacing /var/www/html with your actual DocumentRoot if it differs:

<Directory /var/www/html>
    AllowOverride FileInfo
</Directory>

AllowOverride FileInfo is sufficient for the rewrite directives used by service discovery. If you already have AllowOverride All set for this directory, no change is needed. Next, create or edit the .htaccess file within the DocumentRoot of your Web server and add the following lines:

<IfModule mod_rewrite.c>
  RewriteEngine on
  RewriteRule ^\.well-known/carddav /nextcloud/remote.php/dav [R=301,L]
  RewriteRule ^\.well-known/caldav /nextcloud/remote.php/dav [R=301,L]
  RewriteRule ^\.well-known/webfinger /nextcloud/index.php/.well-known/webfinger [R=301,L]
  RewriteRule ^\.well-known/nodeinfo /nextcloud/index.php/.well-known/nodeinfo [R=301,L]
</IfModule>

Make sure to change /nextcloud to the actual subfolder your Nextcloud instance is running in.

提示

If you put the above directives directly into an Apache configuration file (usually within /etc/apache2/) instead of .htaccess, you need to prepend the first argument of each RewriteRule option with a forward slash /, for example ^/\.well-known/carddav. This is because Apache normalizes paths for the use in .htaccess files by dropping any number of leading slashes, but it does not do so for the use in its main configuration files.

If you are running NGINX, make sure location = /.well-known/carddav { and location = /.well-known/caldav { are properly configured as described in NGINX configuration, adapt to use a subfolder if necessary.

Now change the URL in the client settings to just use:

https://example.com

instead of e.g.

https://example.com/nextcloud/remote.php/dav/principals/username.

There are also several techniques to remedy this, which are described extensively at the Sabre DAV website.

Troubleshooting sharing

Users' Federated Cloud IDs not updated after a domain name change

  1. run Database query

DELETE FROM oc_cards_properties WHERE name = 'CLOUD' AND addressbookid = (select id from oc_addressbooks where principaluri = 'principals/system/system' AND uri = 'system');

  1. run occ commands

occ dav:sync-system-addressbook
occ federation:sync-addressbooks

Troubleshooting contacts & calendar

提示

Please also refer to the troubleshooting article in the groupware section: Troubleshooting.

Troubleshooting data-directory

Moving the data directory / changing the datadirectory path

For local storage, Nextcloud identifies storage by its absolute path on disk. Ideally, the location of the data directory should not change after deployment. If this is a new installation, consider reinstalling with your preferred directory location before moving into production.

警告

If you must change the datadirectory path -- unless the transition is handled carefully -- Nextcloud will treat its content as "new storage." This can trigger duplicate or orphaned files, lost file metadata, and the loss of previously shared links.

For safely moving the data directory, the recommended actions are:

  1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab entry is disabled.
  2. Stop web/app server(s).
  3. Move /data to the new location (ensure you also move hidden/dot files such as .ncdata).
  4. Create a symlink from the original location to the new location.
  5. Ensure permissions are still correct (including for any parent folders).
  6. Restart web/app server(s).
  7. Re-enable Nextcloud's system crontab entry (if applicable).

提示

You may need to configure your web server to support symlinks.

It is also possible to move the data directory without using symlinks, but this requires manually modifying the internal oc_storages database table:

  1. Make sure no cron jobs are running and, if using system cron, that the Nextcloud crontab entry is disabled.
  2. Stop web/app server(s).
  3. Move /data to the new location (ensure you also move hidden/dot files such as .ncdata).
  4. Update the value of datadirectory in your config.php.
  5. Edit the database: In the oc_storages table, update the path portion of the id field of the entry beginning with local::/old-data-dir/ (e.g., change local::/old-data-dir/ to local::/new-data-dir/).
  6. Ensure permissions are still correct (including for any parent folders).
  7. Restart web/app server(s).
  8. Re-enable Nextcloud's system crontab entry (if applicable).

注意

This method is not supported and you risk breaking your database. Always make sure you have up-to-date backups -- including your database -- and a working (tested) restore process before attempting this.

Troubleshooting quota or size issues

Sometimes it can happen that the used space reported in the web UI or with occ user:info $userId does not match the actual data stored in the user's data/$userId/files directory.

提示

Metadata, versions, trashbin and encryption keys are not counted in the used space above. Please refer to the quota documentation for details.

Running the following command can help fix the sizes and quota for a given user:

sudo -E -u www-data php occ files:scan -vvv <user-id>

If encryption was enabled earlier on the instance and disabled later on, it is likely that some size values in the database did not correctly get reset upon decrypting. You can run the following SQL query to reset those after backing up the database:

UPDATE oc_filecache SET unencrypted_size=0 WHERE encrypted=0;

Troubleshooting encrypted files

提示

Please also refer to the troubleshooting section in the encryption chapter: Server-side Encryption.

Fair Use Policy

Nextcloud is open source and you can host it for free on your own server or at a provider.

Nextcloud recommends Using Nextcloud Enterprise for deploying instances with more than 500 users. With that size, issues like a broken server or a data leak become very serious.

If there is an issue with the server, 500 people can't work. A data leak would risk the data of many users. In short, the server should be considered mission-critical. We believe you and your users would have a better experience with Nextcloud Enterprise.

Nextcloud Enterprise is pre-configured and optimised for the needs of professional organisations rather than home users. It comes with support, security and scaling benefits, compliance expertise, and access to our knowledge about running a successful Nextcloud, to get the best possible experience for users and admins. This also reduces the load on our home user forum http://help.nextcloud.com from issues unique to big deployments.

Nextcloud provides some infrastructure components needed for Nextcloud servers to run reliably. This includes notification, our app store and more. To ensure these resources do not get overloaded by administrators who run Nextcloud for thousands of users without providing financial resources to Nextcloud in return, these components are limited and will not work for more than 500 users.

We believe all organisations who run Nextcloud for hundreds of users should be officially supported. We know there can be financial restrictions for non-profit organisations and, as we want everybody to have a chance to get the most out of Nextcloud, we have special offers for NGOs, small schools and other non-profits. Please reach out to talk to us about what is possible through the contact form on our site or ask your system administrator to reach out.

Other issues

Some services like Cloudflare can cause issues by minimizing JavaScript and loading it only when needed. When having issues like a not working login button or creating new users make sure to disable such services first.

Patching Nextcloud

Obtaining a patch

If you found a related pull request on GitHub that solves your issue, or you want to help developers and verify a fix works, you can get a patch for the pull request.

  1. Using https://github.com/nextcloud/server/pull/26396 as an example.
  2. Append .diff to the URL: https://github.com/nextcloud/server/pull/26396.diff
  3. Download the patch to your server e.g. via wget https://github.com/nextcloud/server/pull/26396.diff (this will place 26396.diff in the local directory)
  4. Follow the Applying a patch steps.
  5. If you are on an older Nextcloud version, you might first need to go to the correct backported patch for your version.

backportbot-nextcloud linking to the pull request for an older version.

  1. You can find the appropriate version by looking for a link posted by backportbot-nextcloud to the backport pull request for your release, or by checking for a developer comment with a manual backport link. Use the .diff URL of that backport PR.

Applying a patch

Patching server

  1. Navigate to your Nextcloud server's root directory (the one that contains the status.php file).

  2. Download the patch to your server e.g. via wget https://github.com/nextcloud/server/pull/26396.diff (this will place 26396.diff in the local directory)

  3. Apply the patch with the following command:

    patch -p 1 < ./26396.diff

  4. Alternatively, if the patch command is not available, use:

    git apply --check ./26396.diff
git apply ./26396.diff

Patching apps

  1. Navigate to the root of the app (usually apps/[APPID]/). If you cannot find the app there, use the sudo -E -u www-data php occ app:getpath APPID command to find the path.
  2. Download the patch to your server e.g. via wget https://github.com/nextcloud/<app>/pull/26396.diff (this will place 26396.diff in the local directory)
  3. Apply the patch with the same command as in Patching server.

Reverting a patch

  1. Navigate to the directory where you applied the patch.

  2. Revert the patch with the -R option:

    patch -R -p 1 < ./26396.diff

  3. Alternatively, if the patch command is not available, use:

    git apply --reverse ./26396.diff

Notes and troubleshooting

提示

You may see errors about files not being found, especially when applying patches from GitHub. Patches can include development or test files (for example, files under build/ or tests/) that are not present on your installation. These messages are expected and can be ignored if they refer only to such files.

Code signing

Nextcloud supports code signing for the core releases, and for Nextcloud applications. Code signing gives our users an additional layer of security by ensuring that nobody other than authorized persons can push updates.

It also ensures that all upgrades have been executed properly, so that no files are left behind, and all old files are properly replaced. In the past, invalid updates were a significant source of errors when updating Nextcloud.

FAQ

Why did Nextcloud add code signing?

By supporting Code Signing we add another layer of security by ensuring that nobody other than authorized persons can push updates for applications, and ensuring proper upgrades.

Do we lock down Nextcloud?

The Nextcloud project is open source and always will be. We do not want to make it more difficult for our users to run Nextcloud. Any code signing errors on upgrades will not prevent Nextcloud from running, but will display a warning on the Admin page. For applications that are not tagged "Official" the code signing process is optional.

Not open source anymore?

The Nextcloud project is open source and always will be. The code signing process is optional, though highly recommended. The code check for the core parts of Nextcloud is enabled when the Nextcloud release version branch has been set to stable.

For custom distributions of Nextcloud it is recommended to change the release version branch in version.php to something else than "stable".

Is code signing mandatory for apps?

Code signing is required for all applications on apps.nextcloud.com.

Fixing invalid code integrity messages

A code integrity error message ("Some files have not passed the integrity check…") appears on your Nextcloud admin page under "Overview", which provides the following options:

Links for resolving code integrity warnings.

To debug issues caused by the code integrity check click on "List of invalid files...", and you will be shown a text document listing the different issues. The content of the file will look similar to the following example:

Technical information
=====================
The following list covers which files have failed the integrity check. Please read
the previous linked documentation to learn more about the errors and how to fix
them.

Results
=======
- core
  - INVALID_HASH
      - /index.php
      - /version.php
  - EXTRA_FILE
      - /test.php
- calendar
  - EXCEPTION
      - OC\IntegrityCheck\Exceptions\InvalidSignatureException
      - Signature data not found.

Raw output
==========
Array
(
    [core] => Array
        (
            [INVALID_HASH] => Array
                (
                    [/index.php] => Array
                        (
                            [expected] =>
                            f1c5e2630d784bc9cb02d5a28f55d6f24d06dae2a0fee685f3
                            c2521b050955d9d452769f61454c9ddfa9c308146ade10546c
                            fa829794448eaffbc9a04a29d216
                            [current] =>
                            ce08bf30bcbb879a18b49239a9bec6b8702f52452f88a9d321
                            42cad8d2494d5735e6bfa0d8642b2762c62ca5be49f9bf4ec2
                            31d4a230559d4f3e2c471d3ea094
                        )

                    [/version.php] => Array
                        (
                            [expected] =>
                            c5a03bacae8dedf8b239997901ba1fffd2fe51271d13a00cc4
                            b34b09cca5176397a89fc27381cbb1f72855fa18b69b6f87d7
                            d5685c3b45aee373b09be54742ea
                            [current] =>
                            88a3a92c11db91dec1ac3be0e1c87f862c95ba6ffaaaa3f2c3
                            b8f682187c66f07af3a3b557a868342ef4a271218fe1c1e300
                            c478e6c156c5955ed53c40d06585
                        )

                )

            [EXTRA_FILE] => Array
                (
                    [/test.php] => Array
                        (
                            [expected] =>
                            [current] =>
                            09563164f9904a837f9ca0b5f626db56c838e5098e0ccc1d8b
                            935f68fa03a25c5ec6f6b2d9e44a868e8b85764dafd1605522
                            b4af8db0ae269d73432e9a01e63a
                        )

                )

        )

    [calendar] => Array
        (
            [EXCEPTION] => Array
                (
                    [class] => OC\IntegrityCheck\Exceptions\InvalidSignature
                    Exception
                    [message] => Signature data not found.
                )

        )

)

In above error output it can be seen that:

  1. In the Nextcloud core (that is, the Nextcloud server itself) the files "index.php" and "version.php" do have the wrong version.
  2. In the Nextcloud core the unrequired extra file "/test.php" has been found.
  3. It was not possible to verify the signature of the calendar application.

The solution is to upload the correct "index.php" and "version.php" files, and delete the "test.php" file. For the calendar exception contact the developer of the application. For other means on how to receive support please take a look at https://nextcloud.com/support/. After fixing these problems verify by clicking "Rescan…".

提示

When using a FTP client to upload those files make sure it is using the Binary transfer mode instead of the ASCII transfer mode.

Rescans

Rescans are triggered at installation, and by updates. You may run scans manually with the occ command. The first command scans the Nextcloud server files, and the second command scans the named app. There is not yet a command to manually scan all apps:

occ integrity:check-core
occ integrity:check-app $appid

See Using the occ command to learn more about using occ.

Errors

注意

Please don't modify the mentioned signature.json itself.

The following errors can be encountered when trying to verify a code signature.