Skip to content

feat: Mark systemd timers are preferred method #14718

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CarlSchwan wants to merge 1 commit into
base: master
Choose a base branch
from
+71 −71
Open

feat: Mark systemd timers are preferred method #14718

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 71 additions & 71 deletions admin_manual/configuration_server/background_jobs_configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,52 +46,65 @@ This setting may also be set directly via ``occ`` just like any other configurat
Cron jobs
---------

You can schedule cron jobs in three ways -- using AJAX, Webcron, or cron. The
default method is to use AJAX. However, the recommended method is to use cron.
The following sections describe the differences between each method.
You can schedule cron jobs in three ways -- using AJAX, Webcron, or cron/systemd timers. The
default method is to use AJAX. However, the recommended method is to use systemd timers
or cron. The following sections describe the differences between each method.

AJAX
^^^^
systemd timer
^^^^^^^^^^^^^

**Use case: Single user instance**
If systemd is installed on the system, then systemd timer is the preferred way method for executing
regular tasks. This method enables the execution of scheduled jobs without the
inherent limitations the Web server might have.
Copy link
Copy Markdown
Member

@provokateurin provokateurin May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
inherent limitations the Web server might have.
inherent limitations the web server might have.


The AJAX scheduling method is the default option. Unfortunately, however, it is
also the least reliable. Each time a user visits the Nextcloud page, a single
background job is executed. The advantage of this mechanism is that it does not
require access to the system nor registration with a third-party service. The
disadvantage of this mechanism, when compared to the Webcron service, is that it
requires regular visits to the page for it to be triggered.
This approach requires two files: **nextcloudcron.service** and **nextcloudcron.timer**. Create these two files in ``/etc/systemd/system/``.

.. warning:: Especially when using the Activity app or external storages, where new
files are added, updated or deleted, or when **multiple users** use the server, it
is recommended to use ``cron``.
**nextcloudcron.service** should look like this::

Webcron
^^^^^^^
[Unit]
Description=Nextcloud cron.php job

**Use case: Very small instance** (1–5 users depending on the usage)
[Service]
User=www-data
ExecCondition=php -f /var/www/nextcloud/occ status -e
ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php
KillMode=process

By registering your Nextcloud ``cron.php`` script address at an external webcron
service (for example, easyCron_), you ensure that background jobs are executed
regularly. To use this type of service with your server, you must be able to
access your server using the Internet. For example::
Replace the user ``www-data`` with the user of your http server and ``/var/www/nextcloud/cron.php`` with the location of **cron.php** in your nextcloud directory.

URL to call: http[s]://<domain-of-your-server>/nextcloud/cron.php
The `ExecCondition` checks that the nextcloud instance is operating normally before running the background job, and skips it if otherwise.

.. warning:: Since WebCron is still executed via the web, the webserver in most cases limits the
resources on the execution. To avoid interrupts inside jobs only 1 job is executed
per call. When webcron is called once every 5 minutes this limits your instance to
288 background jobs per day, which is only suitable for very small instances.
For bigger instances, it is recommended to use ``cron``.
The ``KillMode=process`` setting is necessary for external programs that are started by the cron job to keep running after the cron job has finished.

.. _system-cron-configuration-label:
Note that the **.service** unit file does not need an ``[Install]`` section. Please check your setup because we recommended it in earlier versions of this admin manual.

**nextcloudcron.timer** should look like this::

[Unit]
Description=Run Nextcloud cron.php every 5 minutes

[Timer]
OnBootSec=5min
OnUnitActiveSec=5min
Copy link
Copy Markdown
Member

@provokateurin provokateurin May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
OnUnitActiveSec=5min
OnActiveSec=5min

I think we want this, as otherwise a very long running cron would delay the next execution by 5 minutes. If the cron takes a long time, because it has a lot to do, it should run as soon as possible.

Unit=nextcloudcron.service

[Install]
WantedBy=timers.target

The important parts in the timer-unit are ``OnBootSec`` and ``OnUnitActiveSec``. ``OnBootSec`` will start the timer 5 minutes after boot, otherwise, you would have to start it manually after every boot. ``OnUnitActiveSec`` will set a 5-minute timer after the service-unit was last activated.
Copy link
Copy Markdown
Member

@provokateurin provokateurin May 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This would need to be updated too.


Now all that is left is to start and enable the timer by running this command::

systemctl enable --now nextcloudcron.timer

When the option ``--now`` is used with ``enable``, the respective unit will also be started.

.. note:: Selecting the option ``Cron`` in the admin menu for background jobs is not mandatory, because once `cron.php` is executed from the command line or cron service it will set it automatically to ``Cron``.

Cron
^^^^

Using the operating system cron feature is the preferred method for executing
regular tasks. This method enables the execution of scheduled jobs without the
inherent limitations the Web server might have.
If systemd is not installed, you can also use the system cron feature.

To run a cron job on a \*nix system, every 5 minutes, under the default Web
server user (often, ``www-data`` or ``wwwrun``), you must set up the following
Expand Down Expand Up @@ -121,51 +134,38 @@ Which returns::

.. _easyCron: https://www.easycron.com/

systemd
^^^^^^^

If systemd is installed on the system, a systemd timer could be an alternative to a cronjob.

This approach requires two files: **nextcloudcron.service** and **nextcloudcron.timer**. Create these two files in ``/etc/systemd/system/``.

**nextcloudcron.service** should look like this::

[Unit]
Description=Nextcloud cron.php job

[Service]
User=www-data
ExecCondition=php -f /var/www/nextcloud/occ status -e
ExecStart=/usr/bin/php -f /var/www/nextcloud/cron.php
KillMode=process

Replace the user ``www-data`` with the user of your http server and ``/var/www/nextcloud/cron.php`` with the location of **cron.php** in your nextcloud directory.

The `ExecCondition` checks that the nextcloud instance is operating normally before running the background job, and skips it if otherwise.

The ``KillMode=process`` setting is necessary for external programs that are started by the cron job to keep running after the cron job has finished.

Note that the **.service** unit file does not need an ``[Install]`` section. Please check your setup because we recommended it in earlier versions of this admin manual.
AJAX
^^^^

**nextcloudcron.timer** should look like this::
**Use case: Single user instance**

[Unit]
Description=Run Nextcloud cron.php every 5 minutes
The AJAX scheduling method is the default option. Unfortunately, however, it is
also the least reliable. Each time a user visits the Nextcloud page, a single
background job is executed. The advantage of this mechanism is that it does not
require access to the system nor registration with a third-party service. The
disadvantage of this mechanism, when compared to the Webcron service, is that it
requires regular visits to the page for it to be triggered.

[Timer]
OnBootSec=5min
OnUnitActiveSec=5min
Unit=nextcloudcron.service
.. warning:: Especially when using the Activity app or external storages, where new
files are added, updated or deleted, or when **multiple users** use the server, it
is recommended to use ``cron``.

[Install]
WantedBy=timers.target
Webcron
^^^^^^^

The important parts in the timer-unit are ``OnBootSec`` and ``OnUnitActiveSec``. ``OnBootSec`` will start the timer 5 minutes after boot, otherwise, you would have to start it manually after every boot. ``OnUnitActiveSec`` will set a 5-minute timer after the service-unit was last activated.
**Use case: Very small instance** (1–5 users depending on the usage)

Now all that is left is to start and enable the timer by running this command::
By registering your Nextcloud ``cron.php`` script address at an external webcron
service (for example, easyCron_), you ensure that background jobs are executed
regularly. To use this type of service with your server, you must be able to
access your server using the Internet. For example::

systemctl enable --now nextcloudcron.timer
URL to call: http[s]://<domain-of-your-server>/nextcloud/cron.php

When the option ``--now`` is used with ``enable``, the respective unit will also be started.
.. warning:: Since WebCron is still executed via the web, the webserver in most cases limits the
resources on the execution. To avoid interrupts inside jobs only 1 job is executed
per call. When webcron is called once every 5 minutes this limits your instance to
288 background jobs per day, which is only suitable for very small instances.
For bigger instances, it is recommended to use ``cron``.

.. note:: Selecting the option ``Cron`` in the admin menu for background jobs is not mandatory, because once `cron.php` is executed from the command line or cron service it will set it automatically to ``Cron``.
.. _system-cron-configuration-label:
Loading