docs/calendarevents.rst

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