ORG.FREED....TIMEDATE1(5)

💖 ORG.FREED....TIMEDATE1 💖

okay so bestie, gather round, because we're talking about org.freedesktop.timedate1 — the D-Bus interface of systemd-timedated. this is the section 5 page for it, and it's honestly giving main character energy for your system clock. 🕐✨

---

🌸 INTRODUCTION 🌸

so systemd-timedated.service(8) is this system service that can control the system time and all the related settings. and THIS page? it's describing the D-Bus interface. that's it, that's the vibe. 🫶

---

🔥 THE D-BUS API 🔥

the service exposes these interfaces on the bus, and no we are not skipping a single line of it:

node /org/freedesktop/timedate1 {
  interface org.freedesktop.timedate1 {
    methods:
      SetTime(in  x usec_utc,
              in  b relative,
              in  b interactive);
      SetTimezone(in  s timezone,
                  in  b interactive);
      SetLocalRTC(in  b local_rtc,
                  in  b fix_system,
                  in  b interactive);
      SetNTP(in  b use_ntp,
             in  b interactive);
      ListTimezones(out as timezones);
    properties:
      readonly s Timezone = '...';
      readonly b LocalRTC = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b CanNTP = ...;
      readonly b NTP = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly b NTPSynchronized = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t TimeUSec = ...;
      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
      readonly t RTCTimeUSec = ...;
    };
    interface org.freedesktop.DBus.Peer { ... };
    interface org.freedesktop.DBus.Introspectable { ... };
    interface org.freedesktop.DBus.Properties { ... };
};

🛠️ Methods 🛠️

• SetTime() — use this to change the system clock, periodt. you pass a value of microseconds since the UNIX epoch (that's 1 Jan 1970 UTC, iykyk). if relative is true, the usec value you passed gets added to the current system time. if it's false, the current system time gets set to the usec value you passed. and btw, if the system time gets set with this method, the RTC gets updated as well. 💅
• SetTimezone() — use this to set the system timezone. pass a value like "Europe/Berlin" to set the timezone. valid timezones are listed in /usr/share/zoneinfo/zone.tab. and if the RTC is configured to be maintained in local time, it will be updated accordingly. slay.
• SetLocalRTC() — use this to control whether the RTC is in local time or UTC. now listen, it is strongly recommended to maintain the RTC in UTC, ok? but some OSes (Windows, looking at you 👀) maintain the RTC in local time, which might make it necessary to enable this feature. note that this might create various problems as daylight changes could be missed. 😭

if fix_system is "true", the time from the RTC is read again and the system clock is adjusted according to the new setting. if fix_system is "false", the system time is written to the RTC taking the new setting into account.

use fix_system=true in installers and livecds where the RTC is probably more reliable than the system time. use fix_system=false in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC. pick your fighter bestie 🥊

• SetNTP() — use this to control whether the system clock is synchronized with the network using systemd-timesyncd. this will enable and start, or disable and stop, the chosen time synchronization service. ⭐
• ListTimezones() — returns a list of time zones known on the local system as an array of names, literally like ("["Africa/Abidjan", "Africa/Accra", ..., "UTC"]"). 🦋

🔍 Properties 🔍

• Timezone shows the currently configured time zone.
• LocalRTC shows whether the RTC is configured to use UTC (false), or the local time zone (true).
• CanNTP shows whether a service to perform time synchronization over the network is available.
• NTP shows whether such a service is enabled.
• NTPSynchronized shows whether the kernel reports the time as synchronized (c.f. adjtimex(3)).
• TimeUSec and RTCTimeUSec show the current time on the system and in the RTC.

the purpose of those three properties (NTPSynchronized, TimeUSec, RTCTimeUSec) is to allow remote clients to access this information over D-Bus. local clients can access the information directly. no cap. 🙈

whenever the Timezone and LocalRTC settings are changed via the daemon, PropertyChanged signals are sent out to clients which have subscribed. cute, right?

⚠️ note that this service will not inform you about system time changes. for that, use timerfd(3) with CLOCK_REALTIME and TFD_TIMER_CANCEL_ON_SET. that's the whole assignment, bestie.

🔒 Security 🔒

the interactive boolean parameters can be used to control whether polkit should interactively ask the user for authentication credentials if required. 💅

the polkit action for SetTimezone() is org.freedesktop.timedate1.set-timezone. for SetLocalRTC() it is org.freedesktop.timedate1.set-local-rtc, for SetTime() it is org.freedesktop.timedate1.set-time and for SetNTP() it is org.freedesktop.timedate1.set-ntp.

and ListTimezones()? it does not require any privileges at all. free real estate. 👑

---

✨ EXAMPLES ✨

Example 1. Introspect org.freedesktop.timedate1 on the bus — look at her go:

$ gdbus introspect --system \
  --dest org.freedesktop.timedate1 \
  --object-path /org/freedesktop/timedate1

---

🎀 VERSIONING 🎀

these D-Bus interfaces follow the usual interface versioning guidelines. that's the whole section, we love a short queen. 💜

---

🌈 SEE ALSO 🌈

• systemd(1)
• systemd-timedated.service(8)
• timedatectl(1)
• More information on how the system clock and RTC interact

---

📝 NOTES 📝

1. polkit https://www.freedesktop.org/software/polkit/docs/latest/
2. the usual interface versioning guidelines https://0pointer.de/blog/projects/versioning-dbus.html
3. More information on how the system clock and RTC interact https://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html

---

okay and that's the whole page!! this was systemd 262.1, page ORG.FREED....TIMEDATE1(5), and honestly? she ate. go set your timezone correctly bestie, i believe in you 💖✨🦋