man7/time_namespaces.7

   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 2021-03-22 "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 2
  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\(emas
  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 .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:
  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 .PP
  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 /proc/PID/timens_offsets
  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 .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
  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 .PP
  97 In the initial time namespace, the contents of the
  98 .I timens_offsets
  99 file are as follows:
 100 .PP
 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 .PP
 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 .PP
 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 2
 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 .PP
 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 .PP
 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 .PP
 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 .PP
 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 .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
 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 .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
 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 .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
 299 and boot-time clocks have different values in the new time namespace.
 300 .PP
 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 .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),
 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)