diff --git a/admin_manual/configuration_server/background_jobs_configuration.rst b/admin_manual/configuration_server/background_jobs_configuration.rst index 526945586bd..867da96b953 100644 --- a/admin_manual/configuration_server/background_jobs_configuration.rst +++ b/admin_manual/configuration_server/background_jobs_configuration.rst @@ -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. -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]:///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 + 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. + +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 @@ -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]:///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: