| blob | 8a2817be567f2aa1870d9c7b35d91a688513705f |
1 .\" Copyright (c) 2020 by Michael Kerrisk <mtk.manpages@gmail.com>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .\"
6 .TH time_namespaces 7 (date) "Linux man-pages (unreleased)"
7 .SH NAME
8 time_namespaces \- overview of Linux time namespaces
9 .SH DESCRIPTION
10 Time namespaces virtualize the values of two system clocks:
11 .IP \[bu] 3
12 .B CLOCK_MONOTONIC
13 (and likewise
14 .B CLOCK_MONOTONIC_COARSE
15 and
16 .BR CLOCK_MONOTONIC_RAW ),
17 a nonsettable clock that represents monotonic time since\[em]as
18 described by POSIX\[em]"some unspecified point in the past".
19 .IP \[bu]
20 .B CLOCK_BOOTTIME
21 (and likewise
22 .BR CLOCK_BOOTTIME_ALARM ),
23 a nonsettable clock that is identical to
24 .BR CLOCK_MONOTONIC ,
25 except that it also includes any time that the system is suspended.
26 .P
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:
30 .BR clock_gettime (2),
31 .BR clock_nanosleep (2),
32 .BR nanosleep (2),
33 .BR timer_settime (2),
34 .BR timerfd_settime (2),
35 and
36 .IR /proc/uptime .
37 .P
38 Currently, the only way to create a time namespace is by calling
39 .BR unshare (2)
40 with the
41 .B CLONE_NEWTIME
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
51 .IR /proc/ pid /ns/time_for_children
52 symbolic link shows the time namespace in which
53 the children of a process will be created.
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.)
58 .\"
59 .SS \fI/proc/\fPpid\fI/timens_offsets\fP
60 Associated with each time namespace are offsets,
61 expressed with respect to the initial time namespace,
62 that define the values of the monotonic and
63 boot-time clocks in that namespace.
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 .P
70 .in +4n
71 .EX
72 <clock-id> <offset-secs> <offset-nanosecs>
73 .EE
74 .in
75 .P
76 The
77 .I clock-id
78 is a string that identifies the clock whose offsets are being shown.
79 This field is either
80 .IR monotonic ,
81 for
82 .BR CLOCK_MONOTONIC ,
83 or
84 .IR boottime ,
85 for
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.
91 The
92 .I offset-secs
93 value can be negative, subject to restrictions noted below;
94 .I offset-nanosecs
95 is an unsigned value.
96 .P
97 In the initial time namespace, the contents of the
98 .I timens_offsets
99 file are as follows:
100 .P
101 .in +4n
102 .EX
103 $ \fBcat /proc/self/timens_offsets\fP
104 monotonic 0 0
105 boottime 0 0
106 .EE
107 .in
108 .P
109 In a new time namespace that has had no member processes,
110 the clock offsets can be modified by writing newline-terminated
111 records of the same form to the
112 .I timens_offsets
113 file.
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
120 .I timens_offsets
121 file, a process must have the
122 .B CAP_SYS_TIME
123 capability in the user namespace that owns the time namespace.
124 .P
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
141 .B CAP_SYS_TIME
142 capability.
143 .TP
144 .B ERANGE
145 An
146 .I offset-secs
147 value is out of range.
148 In particular;
149 .RS
150 .IP \[bu] 3
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
158 .B KTIME_SEC_MAX
159 (this limits the clock value to a maximum of approximately 146 years).
160 .RE
161 .P
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
168 Use of time namespaces requires a kernel that is configured with the
169 .B CONFIG_TIME_NS
170 option.
171 .P
172 Note that time namespaces do not virtualize the
173 .B CLOCK_REALTIME
174 clock.
175 Virtualization of this clock was avoided for reasons of complexity
176 and overhead within the kernel.
177 .P
178 For compatibility with the initial implementation, when writing a
179 .I clock-id
180 to the
181 .IR /proc/ pid /timens_offsets
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 .
187 For readability, the use of the symbolic names over the numbers is preferred.
188 .P
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.
192 .SH EXAMPLES
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 .P
197 .in +4n
198 .EX
199 $ \fBreadlink /proc/$$/ns/time\fP
200 time:[4026531834]
201 .EE
202 .in
203 .P
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 .P
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 .P
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 .P
240 .in +4n
241 .EX
242 $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP
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
245 .EE
246 .in
247 .P
248 Above, we started the
249 .BR bash (1)
250 shell with the
251 .B \-\-norc
252 option 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 .P
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 .P
270 .in +4n
271 .EX
272 ns2# \fBcat /proc/$$/timens_offsets\fP
273 monotonic 172800 0
274 boottime 604800 0
275 ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP
276 bash: echo: write error: Permission denied
277 .EE
278 .in
279 .P
280 Continuing in the new namespace, we execute
281 .BR uptime (1)
282 and the
283 .I clock_times
284 example program:
285 .P
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 .P
298 From the above output, we can see that the monotonic
299 and boot-time clocks have different values in the new time namespace.
300 .P
301 Examining the
302 .IR /proc/ pid /ns/time
303 and
304 .IR /proc/ pid /ns/time_for_children
305 symbolic links, we see that the shell is a member of the initial time
306 namespace, but its children are created in the new namespace.
307 .P
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 .P
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 .P
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),
339 .BR clock_settime (2),
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)