Run ownCloud Background Jobs Reliably with a Systemd Timer

If ownCloud’s admin page reports that background jobs are not running, queued cleanup and other scheduled work may lag until someone visits the site. On a Linux server managed by systemd, configure the ownCloud background-job mode for Cron and use a timer to run occ system:cron as the web-server account. Current ownCloud Server documentation recommends system cron for regular background work and specifically notes systemd timers as another way to schedule commands.

This guide is for ownCloud Server Classic installed directly on a Linux host. It does not apply to ownCloud Infinite Scale, which has a different architecture, or to the official ownCloud Docker image, which already runs cron internally. For Docker, follow the image’s documented settings instead of creating a second host timer. See the current ownCloud Server background jobs documentation.

Check the command before changing the schedule

A systemd service defines the command to execute; a timer starts that service periodically. First confirm the ownCloud installation path and the HTTP server account. The examples below use /var/www/owncloud and www-data, common on Debian and Ubuntu. Other Linux distributions may use wwwrun, apache, or another account.

Run the ownCloud command manually as that account to distinguish a broken command from a broken schedule:

sudo -u www-data /usr/bin/php -f /var/www/owncloud/occ system:cron

Change the PHP executable and path to occ to match your server. ownCloud recommends using system:cron for background jobs; old guides that schedule cron.php can refer to legacy behavior. A current command may finish without printing a success message, so check its exit status with echo $? immediately afterward: 0 means the command exited successfully. If it returns an error, fix the path, PHP CLI installation, permissions, database connectivity, or ownCloud error first. The timer will repeatedly run the same failing command if you skip this check.

Set ownCloud to Cron mode

In ownCloud’s administrator settings, open the background-jobs or Cron section and choose Cron. You can also set the scheduler from the installation directory with:

cd /var/www/owncloud
sudo -E -u www-data php occ background:cron

This selects Cron mode; the scheduled command remains occ system:cron. The ownCloud manual says this command is equivalent to selecting Cron in the admin page. Cron is preferable for a server that must process jobs reliably because AJAX depends on page visits and may leave work waiting during quiet periods. For a small personal instance, AJAX may be easier, but it is less predictable.

Create the systemd service and timer

Create /etc/systemd/system/owncloudcron.service with your actual HTTP account and ownCloud path:

[Unit]
Description=ownCloud background jobs

[Service]
Type=oneshot
User=www-data
WorkingDirectory=/var/www/owncloud
ExecStart=/usr/bin/php -f /var/www/owncloud/occ system:cron

Type=oneshot tells systemd that the command runs to completion and then exits. Providing the full PHP path avoids depending on the limited PATH available to system services. The working directory helps ownCloud resolve relative paths. Keep the service account aligned with the owner of the ownCloud files and data access. Do not run the job as root.

Next, create /etc/systemd/system/owncloudcron.timer:

[Unit]
Description=Run ownCloud background jobs every 15 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=15min
Unit=owncloudcron.service

[Install]
WantedBy=timers.target

The ownCloud manual recommends a 15-minute cadence for its standard cron example and recognizes systemd timers as an alternative scheduler. This timer starts five minutes after boot and then schedules further runs 15 minutes after the service is activated. If your workload requires another interval, change OnUnitActiveSec deliberately and consider the time each run needs to finish. Avoid configuring another crontab entry for the same command; duplicate schedulers can start redundant runs and make troubleshooting harder.

Tell systemd to reload its unit definitions, then enable and start the timer:

sudo systemctl daemon-reload
sudo systemctl enable --now owncloudcron.timer

daemon-reload is required after creating or editing unit files. Enabling the timer makes it start automatically after future boots; --now starts it in the current session. Enable the timer unit, not just the service.

Find why a run was skipped or failed

Check whether the timer is enabled and when it will run next:

systemctl is-enabled owncloudcron.timer
systemctl list-timers --all owncloudcron.timer
systemctl status owncloudcron.timer

An enabled timer should appear in the timer listing with a next activation. If it does not, confirm the unit filename, reload systemd, and enable the timer again. If the timer shows a run but ownCloud work is still delayed, inspect the service and its logs:

systemctl status owncloudcron.service
sudo journalctl -u owncloudcron.service --since today

Look for a wrong path, inaccessible data directory, missing PHP extension, or a database error. Test the exact command in the service file manually as www-data to reproduce the environment as closely as possible. Also verify that you used the ownCloud command occ system:cron, rather than copying a Nextcloud example that invokes cron.php.

Verify that ownCloud is processing jobs

After one or two timer intervals, confirm that the service has completed successfully and the timer has a later activation scheduled. Then check the background-job status on the ownCloud administrator page. The displayed last-run time should advance, and a stale Cron warning should clear. If systemd reports success but the warning remains, inspect ownCloud’s application log and check whether the web UI is connected to the same instance and database that the command-line installation uses.

For official ownCloud containers, do not install these host units unless you have intentionally disabled the container’s internal scheduler and ownCloud’s current container documentation supports your arrangement. The configuration here is a host-level solution for classic ownCloud on systemd; service names, paths, PHP versions, and container behavior depend on deployment.