1# Introduction
2
3`phosphor-time-manager` is the time manager service that implements D-Bus
4interface `xyz/openbmc_project/Time/EpochTime.interface.yaml`. The user can get
5or set the BMC's time via this interface.
6
7## Configuration
8
9phosphor-time-manager is configured by setting `-D` flags that correspond to
10options in `phosphor-time-manager/meson_options.txt`. The option names become
11C++ preprocessor symbols that control which code is compiled into the program.
12
13- Compile phosphor-time-manager with default options:
14
15  ```
16     meson builddir
17     ninja -C builddir
18  ```
19
20- Compile phosphor-time-manager with some configurable options:
21
22  ```
23     meson builddir -Dbuildtype=minsize  -Dtests=disabled
24     ninja -C builddir
25  ```
26
27- Generate test coverage report:
28
29  ```
30     meson builddir -Db_coverage=true -Dtests=enabled
31     ninja coverage -C builddir test
32  ```
33
34### General usage
35
36The service `xyz.openbmc_project.Time.Manager` provides an object on D-Bus:
37
38- /xyz/openbmc_project/time/bmc
39
40where each object implements interface `xyz.openbmc_project.Time.EpochTime`.
41
42The user can directly get or set the property `Elapsed` of the objects to get or
43set the time. For example on an authenticated session:
44
45- To get BMC's time:
46
47  ```
48  ### With busctl on BMC
49  busctl get-property xyz.openbmc_project.Time.Manager \
50      /xyz/openbmc_project/time/bmc xyz.openbmc_project.Time.EpochTime Elapsed
51
52  ### With REST API on remote host
53  curl -b cjar -k https://${BMC_IP}/xyz/openbmc_project/time/bmc
54  ```
55
56- To set BMC's time:
57
58  ```
59  ### With busctl on BMC
60  busctl set-property xyz.openbmc_project.Time.Manager \
61      /xyz/openbmc_project/time/bmc xyz.openbmc_project.Time.EpochTime \
62      Elapsed t <value-in-microseconds>
63
64  ### With REST API on remote host
65  curl -b cjar -k -H "Content-Type: application/json" -X PUT \
66      -d '{"data": 1487304700000000}' \
67      https://${BMC_IP}/xyz/openbmc_project/time/bmc/attr/Elapsed
68  ```
69
70### Time settings
71
72Getting BMC time is always allowed, but setting the time may not be allowed
73depending on the below two settings in the settings manager.
74
75- TimeSyncMethod
76  - NTP: The time is set via NTP server.
77  - MANUAL: The time is set manually.
78
79A summary of which cases the time can be set on BMC or HOST:
80
81| Mode   | Set BMC Time |
82| ------ | ------------ |
83| NTP    | Fail to set  |
84| MANUAL | OK           |
85
86- To set an NTP [server](https://tf.nist.gov/tf-cgi/servers.cgi):
87
88  ```
89  ### With busctl on BMC
90  busctl set-property  xyz.openbmc_project.Network \
91     /xyz/openbmc_project/network/eth0 \
92     xyz.openbmc_project.Network.EthernetInterface NTPServers \
93     as 1 "<ntp_server>"
94
95  ### With REST API on remote host
96  curl -c cjar -b cjar -k -H "Content-Type: application/json" -X  PUT  -d \
97      '{"data": ["<ntp_server>"] }' \
98      https://${BMC_IP}/xyz/openbmc_project/network/eth0/attr/NTPServers
99  ```
100
101- To go into NTP mode
102
103  ```
104  ### With busctl on BMC
105  busctl set-property xyz.openbmc_project.Settings \
106      /xyz/openbmc_project/time/sync_method xyz.openbmc_project.Time.Synchronization \
107      TimeSyncMethod s "xyz.openbmc_project.Time.Synchronization.Method.NTP"
108
109  ### With REST API on remote host
110  curl -c cjar -b cjar -k -H "Content-Type: application/json" -X  PUT  -d \
111      '{"data": "xyz.openbmc_project.Time.Synchronization.Method.NTP" }' \
112      https://${BMC_IP}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
113  ```
114
115### Special note on changing NTP setting
116
117Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated introduces a
118new beahvior that it checks the NTP services' status during setting time,
119instead of checking the NTP setting:
120
121- When NTP server is set to disabled, and the NTP service is stopping but not
122  stopped, setting time will get an error.
123
124In OpenBMC 2.4 (with systemd v236), the above will always succeed.
125
126This results in [openbmc/openbmc#3459][1], and the related test cases are
127updated to cooperate with this behavior change.
128
129[1]: https://github.com/openbmc/openbmc/issues/3459
130