From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from firstgate.proxmox.com (firstgate.proxmox.com [212.224.123.68]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by lists.proxmox.com (Postfix) with ESMTPS id 8FDAA60F25 for ; Fri, 11 Sep 2020 10:35:33 +0200 (CEST) Received: from firstgate.proxmox.com (localhost [127.0.0.1]) by firstgate.proxmox.com (Proxmox) with ESMTP id 5719B22D5F for ; Fri, 11 Sep 2020 10:35:33 +0200 (CEST) Received: from proxmox-new.maurer-it.com (proxmox-new.maurer-it.com [212.186.127.180]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits)) (No client certificate requested) by firstgate.proxmox.com (Proxmox) with ESMTPS id 136FB22CE5 for ; Fri, 11 Sep 2020 10:35:31 +0200 (CEST) Received: from proxmox-new.maurer-it.com (localhost.localdomain [127.0.0.1]) by proxmox-new.maurer-it.com (Proxmox) with ESMTP id D461C44B4E for ; Fri, 11 Sep 2020 10:35:30 +0200 (CEST) From: Dominik Csapak To: pbs-devel@lists.proxmox.com Date: Fri, 11 Sep 2020 10:35:27 +0200 Message-Id: <20200911083528.31493-3-d.csapak@proxmox.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20200911083528.31493-1-d.csapak@proxmox.com> References: <20200911083528.31493-1-d.csapak@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-SPAM-LEVEL: Spam detection results: 0 AWL -0.519 Adjusted score from AWL reputation of From: address KAM_ASCII_DIVIDERS 0.8 Spam that uses ascii formatting tricks KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment KAM_LAZY_DOMAIN_SECURITY 1 Sending domain does not have any anti-forgery methods NO_DNS_FOR_FROM 0.379 Envelope sender has no MX or A DNS records RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_NONE 0.001 SPF: sender does not publish an SPF Record URIBL_BLOCKED 0.001 ADMINISTRATOR NOTICE: The query to URIBL was blocked. See http://wiki.apache.org/spamassassin/DnsBlocklists#dnsbl-block for more information. [wikipedia.org, freedesktop.org, ietf.org] Subject: [pbs-devel] [PATCH proxmox-backup 3/4] docs: add section for calendar events X-BeenThere: pbs-devel@lists.proxmox.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Proxmox Backup Server development discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 11 Sep 2020 08:35:33 -0000 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 --- 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 ` and :ref:`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 - `_. - 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