]>
Commit | Line | Data |
---|---|---|
5bed06a9 MK |
1 | .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
5fbde956 | 3 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
5bed06a9 MK |
4 | .\" |
5 | .\" | |
4c1c5274 | 6 | .TH time_namespaces 7 (date) "Linux man-pages (unreleased)" |
5bed06a9 MK |
7 | .SH NAME |
8 | time_namespaces \- overview of Linux time namespaces | |
9 | .SH DESCRIPTION | |
10 | Time namespaces virtualize the values of two system clocks: | |
22356d97 | 11 | .IP \(bu 3 |
1ae6b2c7 | 12 | .B CLOCK_MONOTONIC |
5bed06a9 | 13 | (and likewise |
1ae6b2c7 | 14 | .B CLOCK_MONOTONIC_COARSE |
5bed06a9 MK |
15 | and |
16 | .BR CLOCK_MONOTONIC_RAW ), | |
17 | a nonsettable clock that represents monotonic time since\(emas | |
18 | described by POSIX\(em"some unspecified point in the past". | |
19 | .IP \(bu | |
1ae6b2c7 | 20 | .B CLOCK_BOOTTIME |
5bed06a9 MK |
21 | (and likewise |
22 | .BR CLOCK_BOOTTIME_ALARM ), | |
1840148b | 23 | a nonsettable clock that is identical to |
5bed06a9 MK |
24 | .BR CLOCK_MONOTONIC , |
25 | except that it also includes any time that the system is suspended. | |
26 | .PP | |
27 | Thus, the processes in a time namespace share per-namespace values | |
28 | for these clocks. | |
29 | This affects various APIs that measure against these clocks, including: | |
cf406439 | 30 | .BR clock_gettime (2), |
5bed06a9 MK |
31 | .BR clock_nanosleep (2), |
32 | .BR nanosleep (2), | |
cf406439 MK |
33 | .BR timer_settime (2), |
34 | .BR timerfd_settime (2), | |
5bed06a9 MK |
35 | and |
36 | .IR /proc/uptime . | |
37 | .PP | |
38 | Currently, the only way to create a time namespace is by calling | |
39 | .BR unshare (2) | |
40 | with the | |
1ae6b2c7 | 41 | .B CLONE_NEWTIME |
5bed06a9 MK |
42 | flag. |
43 | This call creates a new time namespace but does | |
44 | .I not | |
45 | place the calling process in the new namespace. | |
46 | Instead, the calling process's | |
47 | subsequently created children are placed in the new namespace. | |
48 | This allows clock offsets (see below) for the new namespace | |
49 | to be set before the first process is placed in the namespace. | |
50 | The | |
1ae6b2c7 | 51 | .IR /proc/ pid /ns/time_for_children |
5bed06a9 MK |
52 | symbolic link shows the time namespace in which |
53 | the children of a process will be created. | |
cf406439 MK |
54 | (A process can use a file descriptor opened on |
55 | this symbolic link in a call to | |
56 | .BR setns (2) | |
57 | in order to move into the namespace.) | |
5bed06a9 MK |
58 | .\" |
59 | .SS /proc/PID/timens_offsets | |
60 | Associated with each time namespace are offsets, | |
61 | expressed with respect to the initial time namespace, | |
1840148b MK |
62 | that define the values of the monotonic and |
63 | boot-time clocks in that namespace. | |
5bed06a9 MK |
64 | These offsets are exposed via the file |
65 | .IR /proc/PID/timens_offsets . | |
66 | Within this file, | |
67 | the offsets are expressed as lines consisting of | |
68 | three space-delimited fields: | |
69 | .PP | |
70 | .in +4n | |
71 | .EX | |
72 | <clock-id> <offset-secs> <offset-nanosecs> | |
73 | .EE | |
74 | .in | |
75 | .PP | |
76 | The | |
77 | .I clock-id | |
0953c1b4 MK |
78 | is a string that identifies the clock whose offsets are being shown. |
79 | This field is either | |
80 | .IR monotonic , | |
81 | for | |
5bed06a9 | 82 | .BR CLOCK_MONOTONIC , |
0953c1b4 MK |
83 | or |
84 | .IR boottime , | |
85 | for | |
5bed06a9 MK |
86 | .BR CLOCK_BOOTTIME . |
87 | The remaining fields express the offset (seconds plus nanoseconds) for the | |
88 | clock in this time namespace. | |
89 | These offsets are expressed relative to the clock values in | |
90 | the initial time namespace. | |
cf406439 MK |
91 | The |
92 | .I offset-secs | |
3685736f MK |
93 | value can be negative, subject to restrictions noted below; |
94 | .I offset-nanosecs | |
95 | is an unsigned value. | |
cf406439 MK |
96 | .PP |
97 | In the initial time namespace, the contents of the | |
98 | .I timens_offsets | |
99 | file are as follows: | |
5bed06a9 MK |
100 | .PP |
101 | .in +4n | |
102 | .EX | |
103 | $ \fBcat /proc/self/timens_offsets\fP | |
0953c1b4 MK |
104 | monotonic 0 0 |
105 | boottime 0 0 | |
5bed06a9 MK |
106 | .EE |
107 | .in | |
108 | .PP | |
109 | In a new time namespace that has had no member processes, | |
110 | the clock offsets can be modified by writing newline-terminated | |
cf406439 MK |
111 | records of the same form to the |
112 | .I timens_offsets | |
113 | file. | |
5bed06a9 MK |
114 | The file can be written to multiple times, |
115 | but after the first process has been created in or has entered the namespace, | |
116 | .BR write (2)s | |
117 | on this file fail with the error | |
118 | .BR EACCES . | |
119 | In order to write to the | |
1ae6b2c7 | 120 | .I timens_offsets |
5bed06a9 | 121 | file, a process must have the |
1ae6b2c7 | 122 | .B CAP_SYS_TIME |
5bed06a9 MK |
123 | capability in the user namespace that owns the time namespace. |
124 | .PP | |
3685736f MK |
125 | Writes to the |
126 | .I timens_offsets | |
127 | file can fail with the following errors: | |
128 | .TP | |
129 | .B EINVAL | |
130 | An | |
131 | .I offset-nanosecs | |
132 | value is greater than 999,999,999. | |
133 | .TP | |
134 | .B EINVAL | |
135 | A | |
136 | .I clock-id | |
137 | value is not valid. | |
138 | .TP | |
139 | .B EPERM | |
140 | The caller does not have the | |
1ae6b2c7 | 141 | .B CAP_SYS_TIME |
3685736f MK |
142 | capability. |
143 | .TP | |
144 | .B ERANGE | |
145 | An | |
146 | .I offset-secs | |
147 | value is out of range. | |
148 | In particular; | |
149 | .RS | |
22356d97 | 150 | .IP \(bu 3 |
3685736f MK |
151 | .I offset-secs |
152 | can't be set to a value which would make the current | |
153 | time on the corresponding clock inside the namespace a negative value; and | |
154 | .IP \(bu | |
155 | .I offset-secs | |
156 | can't be set to a value such that the time on the corresponding clock | |
157 | inside the namespace would exceed half of the value of the kernel constant | |
1ae6b2c7 | 158 | .B KTIME_SEC_MAX |
3685736f MK |
159 | (this limits the clock value to a maximum of approximately 146 years). |
160 | .RE | |
161 | .PP | |
5bed06a9 MK |
162 | In a new time namespace created by |
163 | .BR unshare (2), | |
164 | the contents of the | |
165 | .I timens_offsets | |
166 | file are inherited from the time namespace of the creating process. | |
167 | .SH NOTES | |
5bed06a9 MK |
168 | Use of time namespaces requires a kernel that is configured with the |
169 | .B CONFIG_TIME_NS | |
170 | option. | |
171 | .PP | |
172 | Note that time namespaces do not virtualize the | |
1ae6b2c7 | 173 | .B CLOCK_REALTIME |
5bed06a9 MK |
174 | clock. |
175 | Virtualization of this clock was avoided for reasons of complexity | |
176 | and overhead within the kernel. | |
177 | .PP | |
0953c1b4 MK |
178 | For compatibility with the initial implementation, when writing a |
179 | .I clock-id | |
180 | to the | |
1ae6b2c7 | 181 | .IR /proc/ pid /timens_offsets |
0953c1b4 MK |
182 | file, the numerical values of the IDs can be written |
183 | instead of the symbolic names show above; i.e., 1 instead of | |
184 | .IR monotonic , | |
185 | and 7 instead of | |
186 | .IR boottime . | |
713c9be8 | 187 | For readability, the use of the symbolic names over the numbers is preferred. |
0953c1b4 | 188 | .PP |
5bed06a9 MK |
189 | The motivation for adding time namespaces was to allow |
190 | the monotonic and boot-time clocks to maintain consistent values | |
191 | during container migration and checkpoint/restore. | |
a14af333 | 192 | .SH EXAMPLES |
5bed06a9 MK |
193 | The following shell session demonstrates the operation of time namespaces. |
194 | We begin by displaying the inode number of the time namespace | |
195 | of a shell in the initial time namespace: | |
196 | .PP | |
197 | .in +4n | |
198 | .EX | |
199 | $ \fBreadlink /proc/$$/ns/time\fP | |
200 | time:[4026531834] | |
201 | .EE | |
202 | .in | |
203 | .PP | |
204 | Continuing in the initial time namespace, we display the system uptime using | |
205 | .BR uptime (1) | |
206 | and use the | |
207 | .I clock_times | |
208 | example program shown in | |
209 | .BR clock_getres (2) | |
210 | to display the values of various clocks: | |
211 | .PP | |
212 | .in +4n | |
213 | .EX | |
214 | $ \fBuptime \-\-pretty\fP | |
215 | up 21 hours, 17 minutes | |
216 | $ \fB./clock_times\fP | |
217 | CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 36m 41s) | |
218 | CLOCK_TAI : 1585989438.972 (18356 days + 8h 37m 18s) | |
219 | CLOCK_MONOTONIC: 56338.247 (15h 38m 58s) | |
220 | CLOCK_BOOTTIME : 76633.544 (21h 17m 13s) | |
221 | .EE | |
222 | .in | |
223 | .PP | |
224 | We then use | |
225 | .BR unshare (1) | |
226 | to create a time namespace and execute a | |
227 | .BR bash (1) | |
228 | shell. | |
229 | From the new shell, we use the built-in | |
230 | .B echo | |
231 | command to write records to the | |
232 | .I timens_offsets | |
233 | file adjusting the offset for the | |
234 | .B CLOCK_MONOTONIC | |
235 | clock forward 2 days | |
236 | and the offset for the | |
237 | .B CLOCK_BOOTTIME | |
238 | clock forward 7 days: | |
239 | .PP | |
240 | .in +4n | |
241 | .EX | |
242 | $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP | |
0953c1b4 MK |
243 | ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP |
244 | ns2# \fBecho "boottime $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP | |
5bed06a9 MK |
245 | .EE |
246 | .in | |
247 | .PP | |
248 | Above, we started the | |
249 | .BR bash (1) | |
250 | shell with the | |
251 | .B \-\-norc | |
252 | options so that no start-up scripts were executed. | |
253 | This ensures that no child processes are created from the | |
254 | shell before we have a chance to update the | |
255 | .I timens_offsets | |
256 | file. | |
257 | .PP | |
258 | We then use | |
259 | .BR cat (1) | |
260 | to display the contents of the | |
261 | .I timens_offsets | |
262 | file. | |
263 | The execution of | |
264 | .BR cat (1) | |
265 | creates the first process in the new time namespace, | |
266 | after which further attempts to update the | |
267 | .I timens_offsets | |
268 | file produce an error. | |
269 | .PP | |
270 | .in +4n | |
271 | .EX | |
272 | ns2# \fBcat /proc/$$/timens_offsets\fP | |
0953c1b4 MK |
273 | monotonic 172800 0 |
274 | boottime 604800 0 | |
275 | ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP | |
5bed06a9 MK |
276 | bash: echo: write error: Permission denied |
277 | .EE | |
278 | .in | |
279 | .PP | |
280 | Continuing in the new namespace, we execute | |
281 | .BR uptime (1) | |
282 | and the | |
283 | .I clock_times | |
284 | example program: | |
285 | .PP | |
286 | .in +4n | |
287 | .EX | |
288 | ns2# \fBuptime \-\-pretty\fP | |
289 | up 1 week, 21 hours, 18 minutes | |
290 | ns2# \fB./clock_times\fP | |
291 | CLOCK_REALTIME : 1585989457.056 (18356 days + 8h 37m 37s) | |
292 | CLOCK_TAI : 1585989494.057 (18356 days + 8h 38m 14s) | |
293 | CLOCK_MONOTONIC: 229193.332 (2 days + 15h 39m 53s) | |
294 | CLOCK_BOOTTIME : 681488.629 (7 days + 21h 18m 8s) | |
295 | .EE | |
296 | .in | |
297 | .PP | |
298 | From the above output, we can see that the monotonic | |
1840148b | 299 | and boot-time clocks have different values in the new time namespace. |
5bed06a9 MK |
300 | .PP |
301 | Examining the | |
1ae6b2c7 | 302 | .IR /proc/ pid /ns/time |
5bed06a9 | 303 | and |
1ae6b2c7 | 304 | .IR /proc/ pid /ns/time_for_children |
5bed06a9 | 305 | symbolic links, we see that the shell is a member of the initial time |
1840148b | 306 | namespace, but its children are created in the new namespace. |
5bed06a9 MK |
307 | .PP |
308 | .in +4n | |
309 | .EX | |
310 | ns2# \fBreadlink /proc/$$/ns/time\fP | |
311 | time:[4026531834] | |
312 | ns2# \fBreadlink /proc/$$/ns/time_for_children\fP | |
313 | time:[4026532900] | |
314 | ns2# \fBreadlink /proc/self/ns/time\fP # Creates a child process | |
315 | time:[4026532900] | |
316 | .EE | |
317 | .in | |
318 | .PP | |
319 | Returning to the shell in the initial time namespace, | |
320 | we see that the monotonic and boot-time clocks | |
321 | are unaffected by the | |
322 | .I timens_offsets | |
323 | changes that were made in the other time namespace: | |
324 | .PP | |
325 | .in +4n | |
326 | .EX | |
327 | $ \fBuptime \-\-pretty\fP | |
328 | up 21 hours, 19 minutes | |
329 | $ \fB./clock_times\fP | |
330 | CLOCK_REALTIME : 1585989401.971 (18356 days + 8h 38m 51s) | |
331 | CLOCK_TAI : 1585989438.972 (18356 days + 8h 39m 28s) | |
332 | CLOCK_MONOTONIC: 56338.247 (15h 41m 8s) | |
333 | CLOCK_BOOTTIME : 76633.544 (21h 19m 23s) | |
334 | .EE | |
335 | .in | |
336 | .SH SEE ALSO | |
337 | .BR nsenter (1), | |
338 | .BR unshare (1), | |
a8433b3b | 339 | .BR clock_settime (2), |
5bed06a9 MK |
340 | .\" clone3() support for time namespaces is a work in progress |
341 | .\" .BR clone3 (2), | |
342 | .BR setns (2), | |
343 | .BR unshare (2), | |
344 | .BR namespaces (7), | |
345 | .BR time (7) |