From 8c628b39bd474379000ea87695b7c4cf11f2355d Mon Sep 17 00:00:00 2001 From: fabien-joubert <67684689+fabien-joubert@users.noreply.github.com> Date: Sat, 27 Dec 2025 23:42:03 +0100 Subject: [PATCH] docs: clarify backup scheduling scope and common patterns --- doc/040_backup.rst | 73 +++++++++++++++++++++++++++++++++++++++++----- doc/design.rst | 2 ++ 2 files changed, 67 insertions(+), 8 deletions(-) diff --git a/doc/040_backup.rst b/doc/040_backup.rst index 3abd2aeb9..10f8b16f1 100644 --- a/doc/040_backup.rst +++ b/doc/040_backup.rst @@ -664,15 +664,72 @@ snapshot. Scheduling backups ****************** -Restic does not have a built-in way of scheduling backups, as it's a tool -that runs when executed rather than a daemon. There are plenty of different -ways to schedule backup runs on various different platforms, e.g. systemd -and cron on Linux/BSD and Task Scheduler in Windows, depending on one's -needs and requirements. If you don't want to implement your own scheduling, -you can use `resticprofile `__. +.. admonition:: Design note + + Restic intentionally does not provide built-in scheduling or job management. + It is designed to run when executed, rather than as a daemon. Scheduling and + orchestration are therefore considered out of scope and are delegated to the + operating system or external tools. + + This design keeps the restic core simpler, more reliable, and easier to audit, + while allowing it to integrate cleanly into a wide range of environments. + +Scheduling mechanisms +===================== + +Backup scheduling depends on the platform and environment: + +- On Unix-like systems (e.g. BSD, Linux and macOS), ``systemd`` timers are generally preferred when available, + as they provide better error handling, logging, dependency management, and + integration with the system lifecycle. +- ``cron`` remains a widely supported and portable option, especially on + minimal or non-systemd systems. +- On Windows, Task Scheduler can be used to run restic commands at defined + intervals. + +The choice of scheduler depends on the operating system and local constraints, +rather than on restic itself. + +External orchestration tools +============================ + +Several community-maintained tools exist to orchestrate restic backups by +combining configuration, scheduling, hooks, and retention policies. These tools +are optional and not required to use restic. + +Using such tools can reduce boilerplate for some setups, but they are not part +of restic itself and are not required for correct operation. + +.. note:: + + Restic is not affiliated with, nor does it endorse, any third-party + orchestration or automation tools, even if such tools are mentioned explicitly in the + documentation. + +If you don't want to implement your own scheduling, you can use third-party +orchestration tools such as `resticprofile `__. + +Avoiding concurrent runs +======================== + +.. caution:: + + Avoid running overlapping scheduled restic commands against the same + repository. + + While the repository format supports concurrent access, some + operations require exclusive locks and overlapping runs can cause lock + contention, failed backups, or additional maintenance work. + +When scheduling restic to run automatically, use mechanisms that prevent overlapping executions. +Common strategies include: + +- ensuring that scheduled jobs cannot overlap +- using simple locking mechanisms (for example, lock files) +- relying on the scheduler's own guarantees (such as systemd unit semantics). + +See :ref:`locks-design` for details. -When scheduling restic to run recurringly, please make sure to detect already -running instances before starting the backup. Space requirements ****************** diff --git a/doc/design.rst b/doc/design.rst index 90b2d6002..c818b174e 100644 --- a/doc/design.rst +++ b/doc/design.rst @@ -591,6 +591,8 @@ As can be seen from the output of the program ``sha256sum``, the hash matches the plaintext hash from the map included in the tree above, so the correct data has been returned. +.. _locks-design: + Locks =====