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 2021-03-22 "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 .BR CAP_SYS_TIME
 162 capability.
 163 .TP
 164 .B ERANGE
 165 An
 166 .I offset-secs
 167 value is out of range.
 168 In particular;
 169 .RS
 170 .IP \(bu 2
 171 .I offset-secs
 172 can't be set to a value which would make the current
 173 time on the corresponding clock inside the namespace a negative value; and
 174 .IP \(bu
 175 .I offset-secs
 176 can't be set to a value such that the time on the corresponding clock
 177 inside the namespace would exceed half of the value of the kernel constant
 178 .BR KTIME_SEC_MAX
 179 (this limits the clock value to a maximum of approximately 146 years).
 180 .RE
 181 .PP
 182 In a new time namespace created by
 183 .BR unshare (2),
 184 the contents of the
 185 .I timens_offsets
 186 file are inherited from the time namespace of the creating process.
 187 .SH NOTES
 188 Use of time namespaces requires a kernel that is configured with the
 189 .B CONFIG_TIME_NS
 190 option.
 191 .PP
 192 Note that time namespaces do not virtualize the
 193 .BR CLOCK_REALTIME
 194 clock.
 195 Virtualization of this clock was avoided for reasons of complexity
 196 and overhead within the kernel.
 197 .PP
 198 For compatibility with the initial implementation, when writing a
 199 .I clock-id
 200 to the
 201 .IR /proc/[pid]/timens_offsets
 202 file, the numerical values of the IDs can be written
 203 instead of the symbolic names show above; i.e., 1 instead of
 204 .IR monotonic ,
 205 and 7 instead of
 206 .IR boottime .
 207 For readability, the use of the symbolic names over the numbers is preferred.
 208 .PP
 209 The motivation for adding time namespaces was to allow
 210 the monotonic and boot-time clocks to maintain consistent values
 211 during container migration and checkpoint/restore.
 212 .SH EXAMPLES
 213 The following shell session demonstrates the operation of time namespaces.
 214 We begin by displaying the inode number of the time namespace
 215 of a shell in the initial time namespace:
 216 .PP
 217 .in +4n
 218 .EX
 219 $ \fBreadlink /proc/$$/ns/time\fP
 220 time:[4026531834]
 221 .EE
 222 .in
 223 .PP
 224 Continuing in the initial time namespace, we display the system uptime using
 225 .BR uptime (1)
 226 and use the
 227 .I clock_times
 228 example program shown in
 229 .BR clock_getres (2)
 230 to display the values of various clocks:
 231 .PP
 232 .in +4n
 233 .EX
 234 $ \fBuptime \-\-pretty\fP
 235 up 21 hours, 17 minutes
 236 $ \fB./clock_times\fP
 237 CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 36m 41s)
 238 CLOCK_TAI      : 1585989438.972 (18356 days +  8h 37m 18s)
 239 CLOCK_MONOTONIC:      56338.247 (15h 38m 58s)
 240 CLOCK_BOOTTIME :      76633.544 (21h 17m 13s)
 241 .EE
 242 .in
 243 .PP
 244 We then use
 245 .BR unshare (1)
 246 to create a time namespace and execute a
 247 .BR bash (1)
 248 shell.
 249 From the new shell, we use the built-in
 250 .B echo
 251 command to write records to the
 252 .I timens_offsets
 253 file adjusting the offset for the
 254 .B CLOCK_MONOTONIC
 255 clock forward 2 days
 256 and the offset for the
 257 .B CLOCK_BOOTTIME
 258 clock forward 7 days:
 259 .PP
 260 .in +4n
 261 .EX
 262 $ \fBPS1="ns2# " sudo unshare \-T \-\- bash \-\-norc\fP
 263 ns2# \fBecho "monotonic $((2*24*60*60)) 0" > /proc/$$/timens_offsets\fP
 264 ns2# \fBecho "boottime  $((7*24*60*60)) 0" > /proc/$$/timens_offsets\fP
 265 .EE
 266 .in
 267 .PP
 268 Above, we started the
 269 .BR bash (1)
 270 shell with the
 271 .B \-\-norc
 272 options so that no start-up scripts were executed.
 273 This ensures that no child processes are created from the
 274 shell before we have a chance to update the
 275 .I timens_offsets
 276 file.
 277 .PP
 278 We then use
 279 .BR cat (1)
 280 to display the contents of the
 281 .I timens_offsets
 282 file.
 283 The execution of
 284 .BR cat (1)
 285 creates the first process in the new time namespace,
 286 after which further attempts to update the
 287 .I timens_offsets
 288 file produce an error.
 289 .PP
 290 .in +4n
 291 .EX
 292 ns2# \fBcat /proc/$$/timens_offsets\fP
 293 monotonic      172800         0
 294 boottime       604800         0
 295 ns2# \fBecho "boottime $((9*24*60*60)) 0" > /proc/$$/timens_offsets\fP
 296 bash: echo: write error: Permission denied
 297 .EE
 298 .in
 299 .PP
 300 Continuing in the new namespace, we execute
 301 .BR uptime (1)
 302 and the
 303 .I clock_times
 304 example program:
 305 .PP
 306 .in +4n
 307 .EX
 308 ns2# \fBuptime \-\-pretty\fP
 309 up 1 week, 21 hours, 18 minutes
 310 ns2# \fB./clock_times\fP
 311 CLOCK_REALTIME : 1585989457.056 (18356 days +  8h 37m 37s)
 312 CLOCK_TAI      : 1585989494.057 (18356 days +  8h 38m 14s)
 313 CLOCK_MONOTONIC:     229193.332 (2 days + 15h 39m 53s)
 314 CLOCK_BOOTTIME :     681488.629 (7 days + 21h 18m  8s)
 315 .EE
 316 .in
 317 .PP
 318 From the above output, we can see that the monotonic
 319 and boot-time clocks have different values in the new time namespace.
 320 .PP
 321 Examining the
 322 .I /proc/[pid]/ns/time
 323 and
 324 .I /proc/[pid]/ns/time_for_children
 325 symbolic links, we see that the shell is a member of the initial time
 326 namespace, but its children are created in the new namespace.
 327 .PP
 328 .in +4n
 329 .EX
 330 ns2# \fBreadlink /proc/$$/ns/time\fP
 331 time:[4026531834]
 332 ns2# \fBreadlink /proc/$$/ns/time_for_children\fP
 333 time:[4026532900]
 334 ns2# \fBreadlink /proc/self/ns/time\fP   # Creates a child process
 335 time:[4026532900]
 336 .EE
 337 .in
 338 .PP
 339 Returning to the shell in the initial time namespace,
 340 we see that the monotonic and boot-time clocks
 341 are unaffected by the
 342 .I timens_offsets
 343 changes that were made in the other time namespace:
 344 .PP
 345 .in +4n
 346 .EX
 347 $ \fBuptime \-\-pretty\fP
 348 up 21 hours, 19 minutes
 349 $ \fB./clock_times\fP
 350 CLOCK_REALTIME : 1585989401.971 (18356 days +  8h 38m 51s)
 351 CLOCK_TAI      : 1585989438.972 (18356 days +  8h 39m 28s)
 352 CLOCK_MONOTONIC:      56338.247 (15h 41m  8s)
 353 CLOCK_BOOTTIME :      76633.544 (21h 19m 23s)
 354 .EE
 355 .in
 356 .SH SEE ALSO
 357 .BR nsenter (1),
 358 .BR unshare (1),
 359 .BR clock_settime (2),
 360 .\" clone3() support for time namespaces is a work in progress
 361 .\" .BR clone3 (2),
 362 .BR setns (2),
 363 .BR unshare (2),
 364 .BR namespaces (7),
 365 .BR time (7)