calendar-events.adoc

   1 [[chapter_calendar_events]]
   2 ifdef::wiki[]
   3 Calendar Events
   4 ===============
   5 :pve-toplevel:
   6 endif::wiki[]
   7
   8 Schedule Format
   9 ---------------
  10
  11 {pve} has a very flexible scheduling configuration. It is based on the systemd
  12 time calendar event format.footnote:[see `man 7 systemd.time` for more information]
  13 Calendar events may be used to refer to one or more points in time in a
  14 single expression.
  15
  16 Such a calendar event uses the following format:
  17
  18 ----
  19 [WEEKDAY] [[YEARS-]MONTHS-DAYS] [HOURS:MINUTES[:SECONDS]]
  20 ----
  21
  22 This format allows you to configure a set of days on which the job should run.
  23 You can also set one or more start times. It tells the replication scheduler
  24 the moments in time when a job should start.
  25 With this information we, can create a job which runs every workday at 10
  26 PM: `'mon,tue,wed,thu,fri 22'` which could be abbreviated to: `'mon..fri
  27 22'`, most reasonable schedules can be written quite intuitive this way.
  28
  29 NOTE: Hours are formatted in 24-hour format.
  30
  31 To allow a convenient and shorter configuration, one or more repeat times per
  32 guest can be set. They indicate that replications are done on the start-time(s)
  33 itself and the start-time(s) plus all multiples of the repetition value. If
  34 you want to start replication at 8 AM and repeat it every 15 minutes until
  35 9 AM you would use: `'8:00/15'`
  36
  37 Here you see that if no hour separation (`:`), is used the value gets
  38 interpreted as minute. If such a separation is used, the value on the left
  39 denotes the hour(s), and the value on the right denotes the minute(s).
  40 Further, you can use `*` to match all possible values.
  41
  42 To get additional ideas look at
  43 xref:pvesr_schedule_format_examples[more Examples below].
  44
  45 Detailed Specification
  46 ----------------------
  47
  48 weekdays:: Days are specified with an abbreviated English version: `sun, mon,
  49 tue, wed, thu, fri and sat`. You may use multiple days as a comma-separated
  50 list. A range of days can also be set by specifying the start and end day
  51 separated by ``..'', for example `mon..fri`. These formats can be mixed.
  52 If omitted `'*'` is assumed.
  53
  54 time-format:: A time format consists of hours and minutes interval lists.
  55 Hours and minutes are separated by `':'`. Both hour and minute can be list
  56 and ranges of values, using the same format as days.
  57 First are hours, then minutes. Hours can be omitted if not needed. In this
  58 case `'*'` is assumed for the value of hours.
  59 The valid range for values is `0-23` for hours and `0-59` for minutes.
  60
  61 [[pvesr_schedule_format_examples]]
  62 Examples:
  63 ~~~~~~~~~
  64
  65 There are some special values that have a specific meaning:
  66
  67 .Special Values
  68 [width="100%",options="header"]
  69 |================================================================
  70 |Value                                  |Syntax
  71 |`minutely`                             |`*-*-* *:*:00`
  72 |`hourly`                               |`*-*-* *:00:00`
  73 |`daily`                                |`*-*-* 00:00:00`
  74 |`weekly`                               |`mon *-*-* 00:00:00`
  75 |`monthly`                              |`*-*-01 00:00:00`
  76 |`yearly` or `annually`                 | `*-01-01 00:00:00`
  77 |`quarterly`                            |`*-01,04,07,10-01 00:00:00`
  78 |`semiannually` or `semi-annually`      |`*-01,07-01 00:00:00`
  79 |================================================================
  80
  81 .Schedule Examples
  82 [width="100%",options="header"]
  83 |==============================================================================
  84 |Schedule String        |Alternative            |Meaning
  85 |mon,tue,wed,thu,fri    |mon..fri               |Every working day at 0:00
  86 |sat,sun                |sat..sun               |Only on weekends at 0:00
  87 |mon,wed,fri            |--                     |Only on Monday, Wednesday and Friday at 0:00
  88 |12:05                  |12:05                  |Every day at 12:05 PM
  89 |*/5                    |0/5                    |Every five minutes
  90 |mon..wed 30/10         |mon,tue,wed 30/10      |Monday, Tuesday, Wednesday 30, 40 and 50 minutes after every full hour
  91 |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
  92 |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
  93 |12,14,16,18,20,22:5    |12/2:5                 |Every day starting at 12:05 until 22:05, every 2 hours
  94 |*                      |*/1                    |Every minute (minimum interval)
  95 |*-05                   |--                     |On the 5th day of every Month
  96 |Sat *-1..7 15:00       |--                     |First Saturday each Month at 15:00
  97 |2015-10-21             |--                     |21st October 2015 at 00:00
  98 |==============================================================================