projects / proxmox-backup.git / blame
| Commit | Line | Data |
|---|---|---|
| 1eff9a1e DC |
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. | |
| 3bbb70b3 | 16 | They are mostly compatible with systemd's calendar events. |
| 1eff9a1e DC |
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 | ||
| 3bbb70b3 | 30 | Weekdays are specified with the abbreviated English version: |
| 1eff9a1e DC |
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` | |
| 3bbb70b3 | 51 | `yearly` or `annually` `*-01-01 00:00:00` |
| 1eff9a1e DC |
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 | ||
| 3bbb70b3 | 83 | * no Unix timestamps (e.g. `@12345`): instead use date and time to specify |
| 1eff9a1e DC |
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. |