Use org.freedesktop.timedate1 Safely over D-Bus

You will finish with a repeatable way to inspect systemd-timedated over the system D-Bus, list valid timezones, and make a controlled timezone change when you actually need one. The examples match the installed systemd 255 interface described by org.freedesktop.timedate1(5).

Allow about fifteen minutes. You need a shell, the gdbus utility, and a running system bus with systemd-timedated available. Inspection is normally unprivileged. Changing time settings can require polkit authentication and should be treated as an administrative operation.

1. Confirm the installed interface

Start with the exact object and service names. This is a read-only command:

$ dpkg-query -W -f='${Package} ${Version}\n' systemd
systemd 255.4-1ubuntu8.17
$ gdbus introspect --system \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1

The package revision may differ on your machine. The introspection output should include the org.freedesktop.timedate1 interface, methods such as SetTimezone and ListTimezones, and read-only properties including Timezone, LocalRTC, NTP and NTPSynchronized.

Checkpoint: if gdbus reports that it cannot connect to the system bus, stop there. A container, rescue environment or unusual test shell may not have one. Do not replace --system with --session: timedated is a system service, not a per-user service.

2. Read the current state

Properties are exposed through the standard D-Bus properties interface. This asks for the configured timezone without changing anything:

$ gdbus call --system \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1 \
    --method org.freedesktop.DBus.Properties.Get \
    org.freedesktop.timedate1 Timezone
(<string 'Europe/London'>,)

The value is host-specific. The first item is a D-Bus variant containing the string, so do not parse the angle-bracket notation as part of the timezone name. For a broader, human-readable checkpoint, the installed timedatectl client reads the same service:

$ timedatectl show --no-pager \
    -p Timezone -p LocalRTC -p CanNTP -p NTP \
    -p NTPSynchronized -p TimeUSec -p RTCTimeUSec
Timezone=Europe/London
LocalRTC=no
CanNTP=yes
NTP=yes
NTPSynchronized=yes

Clock values and synchronisation can change between commands, so treat those lines as an example shape, not fixed output. LocalRTC=no means the hardware real-time clock is maintained in UTC, which is the recommended arrangement. LocalRTC=yes means it is maintained in local time and can interact badly with daylight-saving changes.

3. List valid timezone names

Do not guess a timezone identifier or copy a desktop display name. Ask timedated for names known to this installation:

$ gdbus call --system \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1 \
    --method org.freedesktop.timedate1.ListTimezones
(['Africa/Abidjan', 'Africa/Accra', ..., 'UTC'],)

The list is returned as an array of strings. The exact order and contents depend on the installed timezone data. Select one exact value, such as Europe/London, Europe/Paris or UTC, only after checking that it appears in your own output.

Checkpoint: to test a candidate without printing the whole list, use the local zoneinfo table:

$ grep -F 'Europe/London' /usr/share/zoneinfo/zone.tab
GB	+5130-0007	Europe/London

This is still only a lookup. It does not alter the clock, RTC or timezone setting.

4. Change the timezone deliberately

Warning: the next call changes persistent system configuration. Running it changes what local time means to applications and, if the RTC is configured as local time, updates the RTC accordingly. Record the current value first so you can undo the change.

$ OLD_TZ=$(timedatectl show --no-pager --value -p Timezone)
$ printf 'Current timezone: %s\n' "$OLD_TZ"
Current timezone: Europe/London
$ gdbus call --system --interactive \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1 \
    --method org.freedesktop.timedate1.SetTimezone \
    'Europe/Paris' true
()

Replace Europe/Paris with a value from the preceding list. The final true is the method's interactive boolean. It permits polkit to ask for authentication if the policy requires it. Without interactive authorisation, a caller that lacks permission may receive a polkit error instead.

Do not put an untrusted string directly into a shell command. If a script supplies the timezone, validate it against ListTimezones first and pass it as one quoted argument. Also avoid changing the timezone in the middle of a batch job whose logs or deadlines depend on local time.

5. Verify and recover

Read the property again after the call. A successful D-Bus method return is useful, but the read-back is the checkpoint that confirms the daemon now reports the requested value:

$ gdbus call --system \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1 \
    --method org.freedesktop.DBus.Properties.Get \
    org.freedesktop.timedate1 Timezone
(<string 'Europe/Paris'>,)

To undo the example, use the value captured before the change. This is another state-changing command and may ask for authentication:

$ gdbus call --system --interactive \
    --dest org.freedesktop.timedate1 \
    --object-path /org/freedesktop/timedate1 \
    --method org.freedesktop.timedate1.SetTimezone \
    "$OLD_TZ" true
()

If the shell that holds OLD_TZ has gone away, retrieve the intended old value from your change record or select a verified value from ListTimezones. Never use an empty value as a shortcut.

6. Keep the other methods in their safety boundaries

SetTime accepts microseconds since 1 January 1970 UTC and can either set an absolute time or add a relative offset. A mistaken integer can move the system clock far into the past or future, so obtain the value from a trusted time source and test the calling code before using it on a live host.

SetLocalRTC chooses between UTC and local time for the hardware clock. The fix_system argument decides the direction of the correction: true reads the RTC into the system clock, while false writes the system time to the RTC. The manpage recommends UTC and reserves the first choice for installers or live media where the RTC is more trustworthy.

SetNTP enables or disables network synchronisation using the selected systemd time synchronisation service. It can start or stop that service, so treat it as a service-disrupting administrative change. Before using it, check CanNTP and record the existing NTP value. NTPSynchronized reports kernel synchronisation; it is not the same thing as the service being enabled.

The interactive argument controls whether polkit may interactively request credentials for the changing methods. ListTimezones needs no privilege. If a privileged call fails, investigate the polkit action and current policy rather than making the D-Bus call more permissive.