[pbs-devel] [PATCH proxmox-backup 1/4] tools/systemd/parse_time: enable */x syntax for calendar events

[pbs-devel] [PATCH proxmox-backup 1/4] tools/systemd/parse_time: enable */x syntax for calendar events

[Dominik Csapak]

we support this in pve, so also support it here to have a more
consistent syntax

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
 src/tools/systemd/parse_time.rs | 27 +++++++++++++++++----------
 1 file changed, 17 insertions(+), 10 deletions(-)

diff --git a/src/tools/systemd/parse_time.rs b/src/tools/systemd/parse_time.rs
index d30a1acc..a1e40139 100644
--- a/src/tools/systemd/parse_time.rs
+++ b/src/tools/systemd/parse_time.rs
@@ -161,10 +161,17 @@ fn parse_date_time_comp(max: usize) -> impl Fn(&str) -> IResult<&str, DateTimeVa
     }
 }
 
-fn parse_date_time_comp_list(max: usize) -> impl Fn(&str) -> IResult<&str, Vec<DateTimeValue>> {
+fn parse_date_time_comp_list(start: u32, max: usize) -> impl Fn(&str) -> IResult<&str, Vec<DateTimeValue>> {
     move |i: &str| {
         if i.starts_with("*") {
-            return Ok((&i[1..], Vec::new()));
+            let i = &i[1..];
+            if i.starts_with("/") {
+                let (n, repeat) = parse_time_comp(max)(&i[1..])?;
+                if repeat > 0 {
+                    return Ok((n, vec![DateTimeValue::Repeated(start, repeat)]));
+                }
+            }
+            return Ok((i, Vec::new()));
         }
 
         separated_nonempty_list(tag(","), parse_date_time_comp(max))(i)
@@ -174,9 +181,9 @@ fn parse_date_time_comp_list(max: usize) -> impl Fn(&str) -> IResult<&str, Vec<D
 fn parse_time_spec(i: &str) -> IResult<&str, (Vec<DateTimeValue>, Vec<DateTimeValue>, Vec<DateTimeValue>)> {
 
     let (i, (hour, minute, opt_second)) = tuple((
-        parse_date_time_comp_list(24),
-        preceded(tag(":"), parse_date_time_comp_list(60)),
-        opt(preceded(tag(":"), parse_date_time_comp_list(60))),
+        parse_date_time_comp_list(0, 24),
+        preceded(tag(":"), parse_date_time_comp_list(0, 60)),
+        opt(preceded(tag(":"), parse_date_time_comp_list(0, 60))),
     ))(i)?;
 
     if let Some(second) = opt_second {
@@ -190,14 +197,14 @@ fn parse_date_spec(i: &str) -> IResult<&str, (Vec<DateTimeValue>, Vec<DateTimeVa
 
     // TODO: implement ~ for days (man systemd.time)
     if let Ok((i, (year, month, day))) = tuple((
-        parse_date_time_comp_list(2200), // the upper limit for systemd, stay compatible
-        preceded(tag("-"), parse_date_time_comp_list(13)),
-        preceded(tag("-"), parse_date_time_comp_list(32)),
+        parse_date_time_comp_list(0, 2200), // the upper limit for systemd, stay compatible
+        preceded(tag("-"), parse_date_time_comp_list(1, 13)),
+        preceded(tag("-"), parse_date_time_comp_list(1, 32)),
     ))(i) {
         Ok((i, (year, month, day)))
     } else if let Ok((i, (month, day))) = tuple((
-        parse_date_time_comp_list(13),
-        preceded(tag("-"), parse_date_time_comp_list(32)),
+        parse_date_time_comp_list(1, 13),
+        preceded(tag("-"), parse_date_time_comp_list(1, 32)),
     ))(i) {
         Ok((i, (Vec::new(), month, day)))
     } else {
-- 
2.20.1

[pbs-devel] [PATCH v2 proxmox-backup 2/4] ui: fix calendarevent examples

[Dominik Csapak]

*/x is valid syntax for us, but not systemd, so to not confuse users
write it like systemd would accept it

also an timespec must at least have hours and minutes

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
no changes from v1 except commit message
even though we support now */x with the previous patch,
i am still in favor of using 0/x in the examples, simply
to stay closer to systemd

 www/form/CalendarEvent.js | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/www/form/CalendarEvent.js b/www/form/CalendarEvent.js
index d05136b9..ddc8fa79 100644
--- a/www/form/CalendarEvent.js
+++ b/www/form/CalendarEvent.js
@@ -4,9 +4,9 @@ Ext.define('PBS.data.CalendarEventExamples', {
 
     field: ['value', 'text'],
     data: [
-	{ value: '*/30', text: Ext.String.format(gettext("Every {0} minutes"), 30) },
+	{ value: '*:0/30', text: Ext.String.format(gettext("Every {0} minutes"), 30) },
 	{ value: 'hourly', text: gettext("Every hour") },
-	{ value: '*/2:00', text: gettext("Every two hours") },
+	{ value: '0/2:00', text: gettext("Every two hours") },
 	{ value: '2,22:30', text: gettext("Every day") + " 02:30, 22:30" },
 	{ value: 'daily', text: gettext("Every day") + " 00:00" },
 	{ value: 'mon..fri', text: gettext("Monday to Friday") + " 00:00" },
-- 
2.20.1

[pbs-devel] [PATCH proxmox-backup 3/4] docs: add section for calendar events

[Dominik Csapak]

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

[pbs-devel] [PATCH proxmox-backup 4/4] ui/docs: add onlineHelp button for syncjobs

[Dominik Csapak]

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
 docs/administration-guide.rst | 1 +
 www/window/SyncJobEdit.js     | 2 ++
 2 files changed, 3 insertions(+)

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index 9320b87f..c48d1f01 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -667,6 +667,7 @@ Use the ``list``, ``show``, ``update``, ``remove`` subcommands of
   └──────┴──────────────┴──────────┴───────────────────────────────────────────┴─────────┘
   # proxmox-backup-manager remote remove pbs2
 
+.. _syncjobs:
 
 Sync Jobs
 ~~~~~~~~~
diff --git a/www/window/SyncJobEdit.js b/www/window/SyncJobEdit.js
index 5b74ccdf..08209e64 100644
--- a/www/window/SyncJobEdit.js
+++ b/www/window/SyncJobEdit.js
@@ -5,6 +5,8 @@ Ext.define('PBS.window.SyncJobEdit', {
 
     userid: undefined,
 
+    onlineHelp: 'syncjobs',
+
     isAdd: true,
 
     subject: gettext('SyncJob'),
-- 
2.20.1

[pbs-devel] applied: [PATCH proxmox-backup 1/4] tools/systemd/parse_time: enable */x syntax for calendar events

[Dietmar Maurer]

applied all 4 patches