1# Introduction
2`phosphor-time-manager` is the time manager service that implements D-Bus
3interface `xyz/openbmc_project/Time/EpochTime.interface.yaml`.
4The user can get or set the BMC's or HOST's time via this interface.
5
6### General usage
7The service `xyz.openbmc_project.Time.Manager` provides two objects on D-Bus:
8* /xyz/openbmc_project/time/bmc
9* /xyz/openbmc_project/time/host
10
11where each object implements interface `xyz.openbmc_project.Time.EpochTime`.
12
13The user can directly get or set the property `Elapsed` of the objects to get or set
14the time. For example on an authenticated session:
15
16* To get BMC's time:
17   ```
18   ### With busctl on BMC
19   busctl get-property xyz.openbmc_project.Time.Manager \
20       /xyz/openbmc_project/time/bmc xyz.openbmc_project.Time.EpochTime Elapsed
21
22   ### With REST API on remote host
23   curl -b cjar -k https://bmc-ip/xyz/openbmc_project/time/bmc
24   ```
25* To set HOST's time:
26   ```
27   ### With busctl on BMC
28   busctl set-property xyz.openbmc_project.Time.Manager \
29       /xyz/openbmc_project/time/host xyz.openbmc_project.Time.EpochTime \
30       Elapsed t <value-in-microseconds>
31
32   ### With REST API on remote host
33   curl -b cjar -k -H "Content-Type: application/json" -X PUT \
34       -d '{"data": 1487304700000000}' \
35       https://bmc-ip/xyz/openbmc_project/time/host/attr/Elapsed
36   ```
37
38### Time settings
39Getting BMC or HOST time is always allowed, but setting the time may not be
40allowed depending on the below two settings in the settings manager.
41
42* TimeSyncMethod
43   * NTP: The time is set via NTP server.
44   * MANUAL: The time is set manually.
45* TimeOwner
46   * BMC: BMC owns the time and can set the time.
47   * HOST: Host owns the time and can set the time.
48   * SPLIT: BMC and Host own separate time.
49   * BOTH: Both BMC and Host can set the time.
50
51A summary of which cases the time can be set on BMC or HOST:
52
53Mode      | Owner | Set BMC Time  | Set Host Time
54--------- | ----- | ------------- | -------------------
55NTP       | BMC   | Fail to set   | Not allowed
56NTP       | HOST  | Not allowed   | Not allowed
57NTP       | SPLIT | Fail to set   | OK
58NTP       | BOTH  | Fail to set   | Not allowed
59MANUAL    | BMC   | OK            | Not allowed
60MANUAL    | HOST  | Not allowed   | OK
61MANUAL    | SPLIT | OK            | OK
62MANUAL    | BOTH  | OK            | OK
63
64### Special note on host on
65When the host is on, the changes of the above time mode/owner are not applied but
66deferred. The changes of the mode/owner are saved to persistent storage.
67
68When the host is off, the saved mode/owner are read from persistent storage and are
69applied.
70
71Note: A user can set the time mode and owner in the settings daemon at any time,
72but the time manager applying them is governed by the above condition.
73