Timers, journalctl --since and many unit settings use the same time syntax, and its only documentation is systemd.time(7). Writing a Go implementation of it for a separate project showed that the man page leaves out a lot of cases and isn’t always right, so the closest thing to a spec is the C code, which (luckily) has comments for many of the odd parts.

The output below comes from systemd 262, with faketime -f '2027-01-01 00:00:00' from libfaketime in front of every systemd-analyze.

Time spans

A time span is a list of numbers and units, which are all added up, so 2h 30min is 150 minutes. systemd-analyze timespan prints the result in microseconds and the way systemd displays it.

Months

The man page says a month is 30.44 days, but systemd uses a year divided by 12, which is 30.4375 days.

$ systemd-analyze timespan 1M 30.44d
Original: 1M
      μs: 2629800000000
   Human: 1month

Original: 30.44d
      μs: 2630016000000
   Human: 1month 3min 36s

A parser that follows the man page is off by 3 minutes and 36 seconds per month.

Case sensitivity

Units are case-sensitive, and M is the only one in uppercase. m is a minute and M is a month, while H, D or Min don’t work at all.

$ systemd-analyze timespan 1m 1H
Original: 1m
      μs: 60000000
   Human: 1min

Failed to parse time span '1H': Invalid argument

Plurals

Units are matched by prefix against a fixed list, and anything left after the match is read as the next number. days is in the list, but hrs, mins and secs aren’t, so hr, min and sec match and the s left over fails.

$ systemd-analyze timespan 1days 1hrs
Original: 1days
      μs: 86400000000
   Human: 1d

Failed to parse time span '1hrs': Invalid argument

Bare numbers

A number without a unit is seconds in most places, even at the end of a longer span. 1hr30 looks like an hour and a half, but it’s an hour and 30 seconds.

$ systemd-analyze timespan 1hr30
Original: 1hr30
      μs: 3630000000
   Human: 1h 30s

Signs and dots

Each number is read with strtoll(), which accepts a leading +, so 5s+5s is 10 seconds. A second decimal point right after a number fails, but a space/unit in between starts a new number.

$ systemd-analyze timespan 5s+5s '12.34 .56' 12.34.56
Original: 5s+5s
      μs: 10000000
   Human: 10s

Original: 12.34 .56
      μs: 12900000
   Human: 12.900000s

Failed to parse time span '12.34.56': Invalid argument

Fractions

Fractions are cut off below a microsecond instead of rounded, and that happens for each number separately, so 0.5us 0.5us is 0.

$ systemd-analyze timespan '0.5us 0.5us' 1.9999999s
Original: 0.5us 0.5us
      μs: 0
   Human: 0

Original: 1.9999999s
      μs: 1999999
   Human: 1.999999s

Infinity

infinity is a valid time span too, even though the man page doesn’t list it. It’s the largest value systemd can store, and settings like TimeoutStopSec= use it to turn the timeout off.

$ systemd-analyze timespan infinity
Original: infinity
      μs: 18446744073709551615
   Human: infinity

Timestamps

A timestamp is a weekday, a date, a time and a timezone, most of which can be left out, or one of a few special forms like now, +5h or @1234567890. systemd-analyze timestamp prints it in the local timezone and as seconds since the epoch.

Two-digit years

Years can have two digits, which the man page shows in an example but doesn’t explain. 00 to 68 become 2000 to 2068, and 69 to 99 become 1969 to 1999.

$ TZ=UTC systemd-analyze timestamp 68-01-01 69-01-01 70-01-01
  Original form: 68-01-01
Normalized form: Sun 2068-01-01 00:00:00 UTC
   UNIX seconds: @3092601600
       From now: 40 years 11 months left

Failed to parse "69-01-01": Numerical result out of range
Hint: this expression is a valid calendar specification. Use 'systemd-analyze calendar "69-01-01"' instead?

  Original form: 70-01-01
Normalized form: -
   UNIX seconds: @0
       From now: -

Timestamps can’t go below the epoch, so 69-01-01 (1969) is out of range. 70-01-01 is exactly the epoch, which is 0, and systemd prints a timestamp of 0 as -. With a 64-bit time_t, the upper limit is 9999-12-30 23:59:59 UTC, a day before the year 9999 ends, so that no timezone can push it into a five-digit year (source).

The conversion itself comes from %y in strptime(), not from systemd. Calendar events have their own, where 00 to 69 become 2000 to 2069 and 70 to 99 become 1970 to 1999, so 69-01-01 is a valid event (and the reason for the hint above).

$ TZ=UTC systemd-analyze calendar 69-01-01 70-01-01
  Original form: 69-01-01
Normalized form: 2069-01-01 00:00:00
    Next elapse: Tue 2069-01-01 00:00:00 UTC
       From now: 42 years 0 months left

  Original form: 70-01-01
Normalized form: 1970-01-01 00:00:00
    Next elapse: never

The T between date and time (as in RFC 3339) only works with four-digit years, which the man page doesn’t mention. With a T, the year is taken as written, so 09 is the year 9 and out of range.

$ TZ=UTC systemd-analyze timestamp 2009-11-10T18:15:22 09-11-10T18:15:22
  Original form: 2009-11-10T18:15:22
Normalized form: Tue 2009-11-10 18:15:22 UTC
   UNIX seconds: @1257876922
       From now: 17 years 1 month ago

Failed to parse "09-11-10T18:15:22": Numerical result out of range

Timezones

The man page lists UTC, Z, offsets and names from the IANA database. Abbreviations only work when the database has a zone by that name or when they belong to the local timezone, so in UTC CET works and PST doesn’t.

$ TZ=UTC systemd-analyze timestamp '2009-11-10 18:15:22 CET' '2009-11-10 18:15:22 PST'
  Original form: 2009-11-10 18:15:22 CET
Normalized form: Tue 2009-11-10 17:15:22 UTC
   UNIX seconds: @1257873322
       From now: 17 years 1 month ago

Failed to parse "2009-11-10 18:15:22 PST": Invalid argument

timedatectl list-timezones shows which names are in the database (e.g., EST is one, but US west coast time is America/Los_Angeles, US/Pacific or PST8PDT). With TZ=America/Los_Angeles, PST and PDT work.

A local abbreviation also decides whether daylight saving time applies, no matter the date. In New York, EDT in December is 4 hours behind UTC, an hour off from EST.

$ TZ=America/New_York systemd-analyze timestamp '2009-12-10 18:15:22 EST' '2009-12-10 18:15:22 EDT'
  Original form: 2009-12-10 18:15:22 EST
Normalized form: Thu 2009-12-10 18:15:22 EST
       (in UTC): Thu 2009-12-10 23:15:22 UTC
   UNIX seconds: @1260486922
       From now: 17 years 0 months ago

  Original form: 2009-12-10 18:15:22 EDT
Normalized form: Thu 2009-12-10 17:15:22 EST
       (in UTC): Thu 2009-12-10 22:15:22 UTC
   UNIX seconds: @1260483322
       From now: 17 years 0 months ago

Weekdays

Unlike units, weekday names don’t care about case, but now, today, yesterday and tomorrow only work in lowercase. A weekday in front of a date also has to match it.

$ TZ=UTC systemd-analyze timestamp 'Wed 2009-11-10' 'TUESDAY 2009-11-10' Today
Failed to parse "Wed 2009-11-10": Invalid argument
Hint: this expression is a valid calendar specification. Use 'systemd-analyze calendar "Wed 2009-11-10"' instead?

  Original form: TUESDAY 2009-11-10
Normalized form: Tue 2009-11-10 00:00:00 UTC
   UNIX seconds: @1257811200
       From now: 17 years 1 month ago

Failed to parse "Today": Invalid argument

2009-11-10 was a Tuesday, so Wed 2009-11-10 is rejected. The hint doesn’t help much, since as a calendar event it never elapses either.

Unix time

@ isn’t limited to an integer. Everything after it is parsed as a time span, so @1h is an hour after the epoch, and even @infinity works.

$ TZ=UTC systemd-analyze timestamp @1h @infinity
  Original form: @1h
Normalized form: Thu 1970-01-01 01:00:00 UTC
   UNIX seconds: @3600
       From now: 56 years 11 months ago

  Original form: @infinity
Normalized form: -
   UNIX seconds: @18446744073709.551615
       From now: -

Syslog format

The format journalctl prints by default, e.g., Dec 31 23:00:00, is accepted, even though the man page doesn’t list it. It has no year, so it’s always the current one, and journalctl --since 'Dec 31 23:00:00' on New Year’s Day finds nothing from the night before.

$ TZ=UTC systemd-analyze timestamp 'Dec 31 23:00:00'
  Original form: Dec 31 23:00:00
Normalized form: Fri 2027-12-31 23:00:00 UTC
   UNIX seconds: @1830294000
       From now: 11 months 30 days left

Spaces

Leading and doubled spaces are fine, but a trailing one breaks the whole timestamp, since the last space is where the timezone is expected to start.

$ TZ=UTC systemd-analyze timestamp ' 2027-01-01  12:00' '2027-01-01 12:00 '
  Original form:  2027-01-01  12:00
Normalized form: Fri 2027-01-01 12:00:00 UTC
   UNIX seconds: @1798804800
       From now: 12h left

Failed to parse "2027-01-01 12:00 ": Invalid argument

Calendar events

A calendar event matches any number of points in time instead of a single one, and it’s what OnCalendar= takes. systemd-analyze calendar shows when it elapses next, and --iterations shows the ones after that.

Shorthands

Shorthands like daily or weekly don’t care about case, unlike today, and the misspelled anually works too, for backwards compatibility.

$ TZ=UTC systemd-analyze calendar DAILY anually
  Original form: DAILY
Normalized form: *-*-* 00:00:00
    Next elapse: Sat 2027-01-02 00:00:00 UTC
       From now: 24h left

  Original form: anually
Normalized form: *-01-01 00:00:00
    Next elapse: Sat 2028-01-01 00:00:00 UTC
       From now: 11 months 30 days left

Repetitions

A repetition without an end has to match at least twice, so *:50/15 fails even though *:50 works. With an end, the same problem is fixed quietly, and *:10..15/10 becomes *:10.

$ TZ=UTC systemd-analyze calendar '*:10..15/10' '*:50/15'
  Original form: *:10..15/10
Normalized form: *-*-* *:10:00
    Next elapse: Fri 2027-01-01 00:10:00 UTC
       From now: 10min left

Failed to parse calendar specification '*:50/15': Invalid argument

Last days

~ instead of - in front of the day counts from the end of the month, so *-*~1 is the last day of every month. Ranges work there, but only from the lower number to the higher one, even though they count backwards, so ~1..3 works and ~3..1 doesn’t. ~ also only goes up to 28.

$ TZ=UTC systemd-analyze calendar --iterations=3 '*-*~1..3' '*-*~3..1' '*-*~29'
  Original form: *-*~1..3
Normalized form: *-*~01..03 00:00:00
    Next elapse: Fri 2027-01-29 00:00:00 UTC
       From now: 4 weeks 0 days left
   Iteration #2: Sat 2027-01-30 00:00:00 UTC
       From now: 4 weeks 1 day left
   Iteration #3: Sun 2027-01-31 00:00:00 UTC
       From now: 4 weeks 2 days left

Failed to parse calendar specification '*-*~3..1': Invalid argument

Failed to parse calendar specification '*-*~29': Invalid argument

Combined with a weekday and a repetition, it can also match the last Monday of a month. ~07/1 is every day of the last 7, and only one of them can be a Monday.

$ TZ=UTC systemd-analyze calendar --iterations=2 'Mon *-05~07/1'
  Original form: Mon *-05~07/1
Normalized form: Mon *-05~07/1 00:00:00
    Next elapse: Mon 2027-05-31 00:00:00 UTC
       From now: 4 months 28 days left
   Iteration #2: Mon 2028-05-29 00:00:00 UTC
       From now: 1 year 4 months left

Weekday ranges

The week starts on Monday, and weekday ranges don’t wrap around its end. Sat..Sun works, but a long weekend from Friday to Monday has to be written as Mon,Fri..Sun (or a full list) instead of Fri..Mon.

$ TZ=UTC systemd-analyze calendar 'Sat..Sun' 'Fri..Mon'
  Original form: Sat..Sun
Normalized form: Sat,Sun *-*-* 00:00:00
    Next elapse: Sat 2027-01-02 00:00:00 UTC
       From now: 24h left

Failed to parse calendar specification 'Fri..Mon': Invalid argument

- works as a range too, also for backwards compatibility, and Mon-Fri turns into Mon..Fri. The man page only mentions ...

$ TZ=UTC systemd-analyze calendar Mon-Fri
  Original form: Mon-Fri
Normalized form: Mon..Fri *-*-* 00:00:00
    Next elapse: Mon 2027-01-04 00:00:00 UTC
       From now: 3 days left

Limits

Years have to be between 1970 and 2199, and anything outside that range is rejected (2200-01-01 is fine as a timestamp, as the hint points out). Inside it, an event can still be valid and never elapse, e.g., February 30 or a weekday that doesn’t match a fixed date. Only the weekday gets a warning. The upper limit also keeps the search for the next elapse from looping forever on impossible dates like February 30 (source).

$ TZ=UTC systemd-analyze calendar '2199-12-31' '2200-01-01' '*-02-30' 'Wed 2027-01-06' 'Wed 2027-01-05'
  Original form: 2199-12-31
Normalized form: 2199-12-31 00:00:00
    Next elapse: Tue 2199-12-31 00:00:00 UTC
       From now: 172 years 11 months left

Failed to parse calendar specification '2200-01-01': Invalid argument
Hint: this expression is a valid timestamp. Use 'systemd-analyze timestamp "2200-01-01"' instead?

  Original form: *-02-30
Normalized form: *-02-30 00:00:00
    Next elapse: never

  Original form: Wed 2027-01-06
Normalized form: Wed 2027-01-06 00:00:00
    Next elapse: Wed 2027-01-06 00:00:00 UTC
       From now: 5 days left

Weekday constraint does not match the fixed date 2027-01-05 (which is a Tue), so this timer will never elapse.
  Original form: Wed 2027-01-05
Normalized form: Wed 2027-01-05 00:00:00
    Next elapse: never

Daylight saving time

The man page doesn’t mention daylight saving time at all. Calendar events use local time unless they have a timezone, so a skipped/repeated hour affects every event in it. In New York, clocks jump from 02:00 to 03:00 on 2027-03-14, so 02:30 doesn’t exist that day.

$ TZ=America/New_York systemd-analyze calendar --base-time='2027-03-13 12:00' --iterations=2 '02:30'
  Original form: 02:30
Normalized form: *-*-* 02:30:00
    Next elapse: Mon 2027-03-15 02:30:00 EDT
       (in UTC): Mon 2027-03-15 06:30:00 UTC
       From now: 2 months 12 days left
   Iteration #2: Tue 2027-03-16 02:30:00 EDT
       (in UTC): Tue 2027-03-16 06:30:00 UTC
       From now: 2 months 13 days left

Instead of moving to 03:30, the event skips 2027-03-14 entirely. On 2027-11-07, clocks go back from 02:00 to 01:00, so the hour from 01:00 to 02:00 happens twice. 01:30 elapses in the first one (EDT), and the next elapse after that is a day later, not an hour.

$ TZ=America/New_York systemd-analyze calendar --base-time='2027-11-06 12:00' --iterations=2 '01:30'
  Original form: 01:30
Normalized form: *-*-* 01:30:00
    Next elapse: Sun 2027-11-07 01:30:00 EDT
       (in UTC): Sun 2027-11-07 05:30:00 UTC
       From now: 10 months 5 days left
   Iteration #2: Mon 2027-11-08 01:30:00 EST
       (in UTC): Mon 2027-11-08 06:30:00 UTC
       From now: 10 months 6 days left

hourly leaves out the repeated hour too, so after 01:00 EDT it elapses next at 02:00 EST, 2 hours later.

$ TZ=America/New_York systemd-analyze calendar --base-time='2027-11-07 00:00' --iterations=3 hourly
  Original form: hourly
Normalized form: *-*-* *:00:00
    Next elapse: Sun 2027-11-07 01:00:00 EDT
       (in UTC): Sun 2027-11-07 05:00:00 UTC
       From now: 10 months 5 days left
   Iteration #2: Sun 2027-11-07 02:00:00 EST
       (in UTC): Sun 2027-11-07 07:00:00 UTC
       From now: 10 months 5 days left
   Iteration #3: Sun 2027-11-07 03:00:00 EST
       (in UTC): Sun 2027-11-07 08:00:00 UTC
       From now: 10 months 5 days left

Timestamps do the opposite in both cases. A time that doesn’t exist moves an hour forward instead of to the next day, and a repeated one means the second time (EST).

$ TZ=America/New_York systemd-analyze timestamp '2027-03-14 02:30' '2027-11-07 01:30'
  Original form: 2027-03-14 02:30
Normalized form: Sun 2027-03-14 03:30:00 EDT
       (in UTC): Sun 2027-03-14 07:30:00 UTC
   UNIX seconds: @1805009400
       From now: 2 months 11 days left

  Original form: 2027-11-07 01:30
Normalized form: Sun 2027-11-07 01:30:00 EST
       (in UTC): Sun 2027-11-07 06:30:00 UTC
   UNIX seconds: @1825569000
       From now: 10 months 5 days left

An event with UTC behind it (e.g., *-*-* 01:30 UTC) isn’t affected.

Timezones in events

Offsets and Z don’t work in calendar events, even though the man page says their timezones are similar to the ones in timestamps.

$ TZ=UTC systemd-analyze calendar '12:00 +05:00' '12:00 Z'
Failed to parse calendar specification '12:00 +05:00': Invalid argument
Hint: this expression is a valid timestamp. Use 'systemd-analyze timestamp "12:00 +05:00"' instead?

Failed to parse calendar specification '12:00 Z': Invalid argument
Hint: this expression is a valid timestamp. Use 'systemd-analyze timestamp "12:00 Z"' instead?

A local abbreviation sets daylight saving time here too, but for every elapse. In New York, 12:00 EST stops elapsing once summer time starts on 2027-03-14, so only 2 of 3 iterations show up.

$ TZ=America/New_York systemd-analyze calendar --base-time='2027-03-12 00:00' --iterations=3 '12:00 EST'
  Original form: 12:00 EST
Normalized form: *-*-* 12:00:00 EST
    Next elapse: Fri 2027-03-12 12:00:00 EST
       (in UTC): Fri 2027-03-12 17:00:00 UTC
       From now: 2 months 9 days left
   Iteration #2: Sat 2027-03-13 12:00:00 EST
       (in UTC): Sat 2027-03-13 17:00:00 UTC
       From now: 2 months 10 days left