From: Dominik Csapak <d.csapak@proxmox.com>
To: pbs-devel@lists.proxmox.com
Subject: [pbs-devel] [PATCH proxmox-backup 3/4] docs: add section for calendar events
Date: Fri, 11 Sep 2020 10:35:27 +0200 [thread overview]
Message-ID: <20200911083528.31493-3-d.csapak@proxmox.com> (raw)
In-Reply-To: <20200911083528.31493-1-d.csapak@proxmox.com>
and move the info defined in 'Schedules' there,
the explanation of calendar events is inspired by the systemd.time
manpage and the pve docs (especially the examples are mostly
copied/adapted from there)
Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
systemd manpage links to hardcoded 'buster' because i did not find
a way to substitute something in a hyperlink, but maybe i am missing
something
docs/administration-guide.rst | 4 +-
docs/calendarevents.rst | 100 ++++++++++++++++++++++++++++++++++
docs/epilog.rst | 3 +
docs/glossary.rst | 11 ----
docs/index.rst | 1 +
5 files changed, 106 insertions(+), 13 deletions(-)
create mode 100644 docs/calendarevents.rst
diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index ca7541d4..9320b87f 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -254,7 +254,7 @@ settings of how many backup snapshots for each interval of ``hourly``,
``daily``, ``weekly``, ``monthly``, ``yearly`` as well as a time-independent
number of backups to keep in that store. :ref:`Pruning <pruning>` and
:ref:`garbage collection <garbage-collection>` can also be configured to run
-periodically based on a configured :term:`schedule` per datastore.
+periodically based on a configured schedule (see :ref:`calendar-events`) per datastore.
Creating a Datastore
^^^^^^^^^^^^^^^^^^^^
@@ -678,7 +678,7 @@ Sync Jobs
Sync jobs are configured to pull the contents of a datastore on a **Remote** to a
local datastore. You can either start a sync job manually on the GUI or
-provide it with a :term:`schedule` to run regularly. You can manage sync jobs
+provide it with a schedule (see :ref:`calendar-events`) to run regularly. You can manage sync jobs
under **Configuration -> Sync Jobs** in the web interface, or using the
``proxmox-backup-manager sync-job`` command:
diff --git a/docs/calendarevents.rst b/docs/calendarevents.rst
new file mode 100644
index 00000000..7ec7da21
--- /dev/null
+++ b/docs/calendarevents.rst
@@ -0,0 +1,100 @@
+
+.. _calendar-events:
+
+Calendar Events
+===============
+
+Introduction and Format
+-----------------------
+
+Certain tasks, for example pruning and garbage collection, need to be
+performed on a regular basis. Proxmox Backup Server uses a format inspired
+by the systemd Time and Date Specification (see `systemd.time manpage`_)
+called `calendar events` for its schedules.
+
+`Calendar events` are expressions to specify one or more points in time.
+They are mostly compatible with systemds calendar events.
+
+The general format is as follows:
+
+.. code-block:: console
+ :caption: Calendar event
+
+ [WEEKDAY] [[YEARS-]MONTHS-DAYS] [HOURS:MINUTES[:SECONDS]]
+
+Note that there either has to be at least a weekday, date or time part.
+If the weekday or date part is omitted, all (week)days are included.
+If the time part is omitted, the time 00:00:00 is implied.
+(e.g. '2020-01-01' refers to '2020-01-01 00:00:00')
+
+Weekdays are specified with the abbreviated english version:
+`mon, tue, wed, thu, fri, sat, sun`.
+
+Each field can contain multiple values in the following formats:
+
+* comma-separated: e.g., 01,02,03
+* as a range: e.g., 01..10
+* as a repetition: e.g, 05/10 (means starting at 5 every 10)
+* and a combination of the above: e.g., 01,05..10,12/02
+* or a `*` for every possible value: e.g., \*:00
+
+There are some special values that have specific meaning:
+
+================================= ==============================
+Value Syntax
+================================= ==============================
+`minutely` `*-*-* *:*:00`
+`hourly` `*-*-* *:00:00`
+`daily` `*-*-* 00:00:00`
+`weekly` `mon *-*-* 00:00:00`
+`monthly` `*-*-01 00:00:00`
+`yearly` or `annualy` `*-01-01 00:00:00`
+`quarterly` `*-01,04,07,10-01 00:00:00`
+`semiannually` or `semi-annually` `*-01,07-01 00:00:00`
+================================= ==============================
+
+
+Here is a table with some useful examples:
+
+======================== ============================= ===================================
+Example Alternative Explanation
+======================== ============================= ===================================
+`mon,tue,wed,thu,fri` `mon..fri` Every working day at 00:00
+`sat,sun` `sat..sun` Only on weekends at 00:00
+`mon,wed,fri` -- Monday, Wednesday, Friday at 00:00
+`12:05` -- Every day at 12:05 PM
+`*:00/5` `0/1:0/5` Every five minutes
+`mon..wed *:30/10` `mon,tue,wed *:30/10` Monday, Tuesday, Wednesday 30, 40 and 50 minutes after every full hour
+`mon..fri 8..17,22:0/15` -- Every working day every 15 minutes between 8 AM and 6 PM and between 10 PM and 11 PM
+`fri 12..13:5/20` `fri 12,13:5/20` Friday at 12:05, 12:25, 12:45, 13:05, 13:25 and 13:45
+`12,14,16,18,20,22:5` `12/2:5` Every day starting at 12:05 until 22:05, every 2 hours
+`*:*` `0/1:0/1` Every minute (minimum interval)
+`*-05` -- On the 5th day of every Month
+`Sat *-1..7 15:00` -- First Saturday each Month at 15:00
+`2015-10-21` -- 21st October 2015 at 00:00
+======================== ============================= ===================================
+
+
+Differences to systemd
+----------------------
+
+Not all features of systemd calendar events are implemented:
+
+* no unix timestamps (e.g. `@12345`): instead use date and time to specify
+ a specific point in time
+* no timezone: all schedules use the set timezone on the server
+* no sub-second resolution
+* no reverse day syntax (e.g. 2020-03~01)
+* no repetition of ranges (e.g. 1..10/2)
+
+Notes on scheduling
+-------------------
+
+In `Proxmox Backup`_ scheduling for most tasks is done in the
+`proxmox-backup-proxy`. This daemon checks all job schedules
+if they are due every minute. This means that even if
+`calendar events` can contain seconds, it will only be checked
+once a minute.
+
+Also, all schedules will be checked against the timezone set
+in the `Proxmox Backup`_ server.
diff --git a/docs/epilog.rst b/docs/epilog.rst
index 1e27d23d..06873a21 100644
--- a/docs/epilog.rst
+++ b/docs/epilog.rst
@@ -38,3 +38,6 @@
.. _RFC3399: https://tools.ietf.org/html/rfc3339
.. _UTC: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
.. _ISO Week date: https://en.wikipedia.org/wiki/ISO_week_date
+
+.. _systemd.time manpage: https://manpages.debian.org/buster/systemd/systemd.time.7.en.html
+
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 913b6f25..37e32a0e 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -51,14 +51,3 @@ Glossary
A remote Proxmox Backup Server installation and credentials for a user on it.
You can pull datastores from a remote to a local datastore in order to
have redundant backups.
-
- Schedule
-
- Certain tasks, for example pruning and garbage collection, need to be
- performed on a regular basis. Proxmox Backup Server uses a subset of the
- `systemd Time and Date Specification
- <https://www.freedesktop.org/software/systemd/man/systemd.time.html#>`_.
- The subset currently supports time of day specifications and weekdays, in
- addition to the shorthand expressions 'minutely', 'hourly', 'daily'.
- There is no support for specifying timezones, the tasks are run in the
- timezone configured on the server.
diff --git a/docs/index.rst b/docs/index.rst
index dfa60cb9..cfb9b69f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -37,6 +37,7 @@ in the section entitled "GNU Free Documentation License".
command-syntax.rst
file-formats.rst
backup-protocol.rst
+ calendarevents.rst
glossary.rst
GFDL.rst
--
2.20.1
next prev parent reply other threads:[~2020-09-11 8:35 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-09-11 8:35 [pbs-devel] [PATCH proxmox-backup 1/4] tools/systemd/parse_time: enable */x syntax " Dominik Csapak
2020-09-11 8:35 ` [pbs-devel] [PATCH v2 proxmox-backup 2/4] ui: fix calendarevent examples Dominik Csapak
2020-09-11 8:35 ` Dominik Csapak [this message]
2020-09-11 8:35 ` [pbs-devel] [PATCH proxmox-backup 4/4] ui/docs: add onlineHelp button for syncjobs Dominik Csapak
2020-09-11 10:17 ` [pbs-devel] applied: [PATCH proxmox-backup 1/4] tools/systemd/parse_time: enable */x syntax for calendar events Dietmar Maurer
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20200911083528.31493-3-d.csapak@proxmox.com \
--to=d.csapak@proxmox.com \
--cc=pbs-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox