man7/time_namespaces.7

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