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 time via this interface.
5
6### General usage
7The service `xyz.openbmc_project.Time.Manager` provides an object on D-Bus:
8* /xyz/openbmc_project/time/bmc
9
10where each object implements interface `xyz.openbmc_project.Time.EpochTime`.
11
12The user can directly get or set the property `Elapsed` of the objects to get or set
13the time. For example on an authenticated session:
14
15* To get BMC's time:
16   ```
17   ### With busctl on BMC
18   busctl get-property xyz.openbmc_project.Time.Manager \
19       /xyz/openbmc_project/time/bmc xyz.openbmc_project.Time.EpochTime Elapsed
20
21   ### With REST API on remote host
22   curl -b cjar -k https://${BMC_IP}/xyz/openbmc_project/time/bmc
23   ```
24* To set BMC's time:
25   ```
26   ### With busctl on BMC
27   busctl set-property xyz.openbmc_project.Time.Manager \
28       /xyz/openbmc_project/time/bmc xyz.openbmc_project.Time.EpochTime \
29       Elapsed t <value-in-microseconds>
30
31   ### With REST API on remote host
32   curl -b cjar -k -H "Content-Type: application/json" -X PUT \
33       -d '{"data": 1487304700000000}' \
34       https://${BMC_IP}/xyz/openbmc_project/time/bmc/attr/Elapsed
35   ```
36
37### Time settings
38Getting BMC time is always allowed, but setting the time may not be
39allowed depending on the below two settings in the settings manager.
40
41* TimeSyncMethod
42   * NTP: The time is set via NTP server.
43   * MANUAL: The time is set manually.
44
45A summary of which cases the time can be set on BMC or HOST:
46
47Mode      | Set BMC Time
48--------- | -------------
49NTP       | Fail to set
50MANUAL    | OK
51
52* To set an NTP [server](https://tf.nist.gov/tf-cgi/servers.cgi):
53   ```
54   ### With busctl on BMC
55   busctl set-property  xyz.openbmc_project.Network \
56      /xyz/openbmc_project/network/eth0 \
57      xyz.openbmc_project.Network.EthernetInterface NTPServers \
58      as 1 "<ntp_server>"
59
60   ### With REST API on remote host
61   curl -c cjar -b cjar -k -H "Content-Type: application/json" -X  PUT  -d \
62       '{"data": ["<ntp_server>"] }' \
63       https://${BMC_IP}/xyz/openbmc_project/network/eth0/attr/NTPServers
64   ```
65
66* To go into NTP mode
67   ```
68   ### With busctl on BMC
69   busctl set-property xyz.openbmc_project.Settings \
70       /xyz/openbmc_project/time/sync_method xyz.openbmc_project.Time.Synchronization \
71       TimeSyncMethod s "xyz.openbmc_project.Time.Synchronization.Method.NTP"
72
73   ### With REST API on remote host
74   curl -c cjar -b cjar -k -H "Content-Type: application/json" -X  PUT  -d \
75       '{"data": "xyz.openbmc_project.Time.Synchronization.Method.NTP" }' \
76       https://${BMC_IP}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
77   ```
78
79### Special note on changing NTP setting
80Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated introduces
81a new beahvior that it checks the NTP services' status during setting time,
82instead of checking the NTP setting:
83
84* When NTP server is set to disabled, and the NTP service is stopping but not
85   stopped, setting time will get an error.
86
87In OpenBMC 2.4 (with systemd v236), the above will always succeed.
88
89This results in [openbmc/openbmc#3459][1], and the related test cases are
90updated to cooperate with this behavior change.
91
92### Special note on host on
93When the host is on, the changes of the above time mode are not applied but
94deferred. The changes of the mode are saved to persistent storage.
95
96When the host is off, the saved mode are read from persistent storage and are
97applied.
98
99Note: A user can set the time mode in the settings daemon at any time,
100but the time manager applying them is governed by the above condition.
101
102
103[1]: https://github.com/openbmc/openbmc/issues/3459
104