docs/calendarevents.rst

   1 .. _calendar-event-scheduling:
   2
   3 Calendar Events
   4 ===============
   5
   6 Introduction and Format
   7 -----------------------
   8
   9 Certain tasks, for example pruning and garbage collection, need to be
  10 performed on a regular basis. Proxmox Backup Server uses a format inspired
  11 by the systemd Time and Date Specification (see `systemd.time manpage`_)
  12 called `calendar events` for its schedules.
  13
  14 `Calendar events` are expressions to specify one or more points in time.
  15 They are mostly compatible with systemd's calendar events.
  16
  17 The general format is as follows:
  18
  19 .. code-block:: console
  20   :caption: Calendar event
  21
  22   [WEEKDAY] [[YEARS-]MONTHS-DAYS] [HOURS:MINUTES[:SECONDS]]
  23
  24 Note that there either has to be at least a weekday, date or time part.
  25 If the weekday or date part is omitted, all (week)days are included.
  26 If the time part is omitted, the time 00:00:00 is implied.
  27 (e.g. '2020-01-01' refers to '2020-01-01 00:00:00')
  28
  29 Weekdays are specified with the abbreviated English version:
  30 `mon, tue, wed, thu, fri, sat, sun`.
  31
  32 Each field can contain multiple values in the following formats:
  33
  34 * comma-separated: e.g.,  01,02,03
  35 * as a range: e.g., 01..10
  36 * as a repetition: e.g, 05/10 (means starting at 5 every 10)
  37 * and a combination of the above: e.g., 01,05..10,12/02
  38 * or a `*` for every possible value: e.g., \*:00
  39
  40 There are some special values that have specific meaning:
  41
  42 =================================  ==============================
  43 Value                              Syntax
  44 =================================  ==============================
  45 `minutely`                         `*-*-* *:*:00`
  46 `hourly`                           `*-*-* *:00:00`
  47 `daily`                            `*-*-* 00:00:00`
  48 `weekly`                           `mon *-*-* 00:00:00`
  49 `monthly`                          `*-*-01 00:00:00`
  50 `yearly` or `annually`              `*-01-01 00:00:00`
  51 `quarterly`                        `*-01,04,07,10-01 00:00:00`
  52 `semiannually` or `semi-annually`  `*-01,07-01 00:00:00`
  53 =================================  ==============================
  54
  55
  56 Here is a table with some useful examples:
  57
  58 ======================== =============================  ===================================
  59 Example                  Alternative                    Explanation
  60 ======================== =============================  ===================================
  61 `mon,tue,wed,thu,fri`    `mon..fri`                     Every working day at 00:00
  62 `sat,sun`                `sat..sun`                     Only on weekends at 00:00
  63 `mon,wed,fri`            --                             Monday, Wednesday, Friday at 00:00
  64 `12:05`                  --                             Every day at 12:05 PM
  65 `*:00/5`                 `0/1:0/5`                      Every five minutes
  66 `mon..wed *:30/10`       `mon,tue,wed *:30/10`          Monday, Tuesday, Wednesday 30, 40 and 50 minutes after every full hour
  67 `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
  68 `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
  69 `12,14,16,18,20,22:5`    `12/2:5`                       Every day starting at 12:05 until 22:05, every 2 hours
  70 `*:*`                    `0/1:0/1`                      Every minute (minimum interval)
  71 `*-05`                   --                             On the 5th day of every Month
  72 `Sat *-1..7 15:00`       --                             First Saturday each Month at 15:00
  73 `2015-10-21`             --                             21st October 2015 at 00:00
  74 ======================== =============================  ===================================
  75
  76
  77 Differences to systemd
  78 ----------------------
  79
  80 Not all features of systemd calendar events are implemented:
  81
  82 * no Unix timestamps (e.g. `@12345`): instead use date and time to specify
  83   a specific point in time
  84 * no timezone: all schedules use the set timezone on the server
  85 * no sub-second resolution
  86 * no reverse day syntax (e.g. 2020-03~01)
  87 * no repetition of ranges (e.g. 1..10/2)
  88
  89 Notes on scheduling
  90 -------------------
  91
  92 In `Proxmox Backup`_ scheduling for most tasks is done in the
  93 `proxmox-backup-proxy`. This daemon checks all job schedules
  94 if they are due every minute. This means that even if
  95 `calendar events` can contain seconds, it will only be checked
  96 once a minute.
  97
  98 Also, all schedules will be checked against the timezone set
  99 in the `Proxmox Backup`_ server.