man7/user_namespaces.7

   1 .\" Copyright (c) 2013, 2014 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (c) 2012, 2014 by Eric W. Biederman <ebiederm@xmission.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\"
  27 .TH USER_NAMESPACES 7 2021-03-22 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 user_namespaces \- overview of Linux user namespaces
  30 .SH DESCRIPTION
  31 For an overview of namespaces, see
  32 .BR namespaces (7).
  33 .PP
  34 User namespaces isolate security-related identifiers and attributes,
  35 in particular,
  36 user IDs and group IDs (see
  37 .BR credentials (7)),
  38 the root directory,
  39 keys (see
  40 .BR keyrings (7)),
  41 .\" FIXME: This page says very little about the interaction
  42 .\" of user namespaces and keys. Add something on this topic.
  43 and capabilities (see
  44 .BR capabilities (7)).
  45 A process's user and group IDs can be different
  46 inside and outside a user namespace.
  47 In particular,
  48 a process can have a normal unprivileged user ID outside a user namespace
  49 while at the same time having a user ID of 0 inside the namespace;
  50 in other words,
  51 the process has full privileges for operations inside the user namespace,
  52 but is unprivileged for operations outside the namespace.
  53 .\"
  54 .\" ============================================================
  55 .\"
  56 .SS Nested namespaces, namespace membership
  57 User namespaces can be nested;
  58 that is, each user namespace\(emexcept the initial ("root")
  59 namespace\(emhas a parent user namespace,
  60 and can have zero or more child user namespaces.
  61 The parent user namespace is the user namespace
  62 of the process that creates the user namespace via a call to
  63 .BR unshare (2)
  64 or
  65 .BR clone (2)
  66 with the
  67 .BR CLONE_NEWUSER
  68 flag.
  69 .PP
  70 The kernel imposes (since version 3.11) a limit of 32 nested levels of
  71 .\" commit 8742f229b635bf1c1c84a3dfe5e47c814c20b5c8
  72 user namespaces.
  73 .\" FIXME Explain the rationale for this limit. (What is the rationale?)
  74 Calls to
  75 .BR unshare (2)
  76 or
  77 .BR clone (2)
  78 that would cause this limit to be exceeded fail with the error
  79 .BR EUSERS .
  80 .PP
  81 Each process is a member of exactly one user namespace.
  82 A process created via
  83 .BR fork (2)
  84 or
  85 .BR clone (2)
  86 without the
  87 .BR CLONE_NEWUSER
  88 flag is a member of the same user namespace as its parent.
  89 A single-threaded process can join another user namespace with
  90 .BR setns (2)
  91 if it has the
  92 .BR CAP_SYS_ADMIN
  93 in that namespace;
  94 upon doing so, it gains a full set of capabilities in that namespace.
  95 .PP
  96 A call to
  97 .BR clone (2)
  98 or
  99 .BR unshare (2)
 100 with the
 101 .BR CLONE_NEWUSER
 102 flag makes the new child process (for
 103 .BR clone (2))
 104 or the caller (for
 105 .BR unshare (2))
 106 a member of the new user namespace created by the call.
 107 .PP
 108 The
 109 .BR NS_GET_PARENT
 110 .BR ioctl (2)
 111 operation can be used to discover the parental relationship
 112 between user namespaces; see
 113 .BR ioctl_ns (2).
 114 .\"
 115 .\" ============================================================
 116 .\"
 117 .SS Capabilities
 118 The child process created by
 119 .BR clone (2)
 120 with the
 121 .BR CLONE_NEWUSER
 122 flag starts out with a complete set
 123 of capabilities in the new user namespace.
 124 Likewise, a process that creates a new user namespace using
 125 .BR unshare (2)
 126 or joins an existing user namespace using
 127 .BR setns (2)
 128 gains a full set of capabilities in that namespace.
 129 On the other hand,
 130 that process has no capabilities in the parent (in the case of
 131 .BR clone (2))
 132 or previous (in the case of
 133 .BR unshare (2)
 134 and
 135 .BR setns (2))
 136 user namespace,
 137 even if the new namespace is created or joined by the root user
 138 (i.e., a process with user ID 0 in the root namespace).
 139 .PP
 140 Note that a call to
 141 .BR execve (2)
 142 will cause a process's capabilities to be recalculated in the usual way (see
 143 .BR capabilities (7)).
 144 Consequently,
 145 unless the process has a user ID of 0 within the namespace,
 146 or the executable file has a nonempty inheritable capabilities mask,
 147 the process will lose all capabilities.
 148 See the discussion of user and group ID mappings, below.
 149 .PP
 150 A call to
 151 .BR clone (2)
 152 or
 153 .BR unshare (2)
 154 using the
 155 .BR CLONE_NEWUSER
 156 flag
 157 or a call to
 158 .BR setns (2)
 159 that moves the caller into another user namespace
 160 sets the "securebits" flags
 161 (see
 162 .BR capabilities (7))
 163 to their default values (all flags disabled) in the child (for
 164 .BR clone (2))
 165 or caller (for
 166 .BR unshare (2)
 167 or
 168 .BR setns (2)).
 169 Note that because the caller no longer has capabilities
 170 in its original user namespace after a call to
 171 .BR setns (2),
 172 it is not possible for a process to reset its "securebits" flags while
 173 retaining its user namespace membership by using a pair of
 174 .BR setns (2)
 175 calls to move to another user namespace and then return to
 176 its original user namespace.
 177 .PP
 178 The rules for determining whether or not a process has a capability
 179 in a particular user namespace are as follows:
 180 .IP 1. 3
 181 A process has a capability inside a user namespace
 182 if it is a member of that namespace and
 183 it has the capability in its effective capability set.
 184 A process can gain capabilities in its effective capability
 185 set in various ways.
 186 For example, it may execute a set-user-ID program or an
 187 executable with associated file capabilities.
 188 In addition,
 189 a process may gain capabilities via the effect of
 190 .BR clone (2),
 191 .BR unshare (2),
 192 or
 193 .BR setns (2),
 194 as already described.
 195 .\" In the 3.8 sources, see security/commoncap.c::cap_capable():
 196 .IP 2.
 197 If a process has a capability in a user namespace,
 198 then it has that capability in all child (and further removed descendant)
 199 namespaces as well.
 200 .IP 3.
 201 .\" * The owner of the user namespace in the parent of the
 202 .\" * user namespace has all caps.
 203 When a user namespace is created, the kernel records the effective
 204 user ID of the creating process as being the "owner" of the namespace.
 205 .\" (and likewise associates the effective group ID of the creating process
 206 .\" with the namespace).
 207 A process that resides
 208 in the parent of the user namespace
 209 .\" See kernel commit 520d9eabce18edfef76a60b7b839d54facafe1f9 for a fix
 210 .\" on this point
 211 and whose effective user ID matches the owner of the namespace
 212 has all capabilities in the namespace.
 213 .\"     This includes the case where the process executes a set-user-ID
 214 .\"     program that confers the effective UID of the creator of the namespace.
 215 By virtue of the previous rule,
 216 this means that the process has all capabilities in all
 217 further removed descendant user namespaces as well.
 218 The
 219 .B NS_GET_OWNER_UID
 220 .BR ioctl (2)
 221 operation can be used to discover the user ID of the owner of the namespace;
 222 see
 223 .BR ioctl_ns (2).
 224 .\"
 225 .\" ============================================================
 226 .\"
 227 .SS Effect of capabilities within a user namespace
 228 Having a capability inside a user namespace
 229 permits a process to perform operations (that require privilege)
 230 only on resources governed by that namespace.
 231 In other words, having a capability in a user namespace permits a process
 232 to perform privileged operations on resources that are governed by (nonuser)
 233 namespaces owned by (associated with) the user namespace
 234 (see the next subsection).
 235 .PP
 236 On the other hand, there are many privileged operations that affect
 237 resources that are not associated with any namespace type,
 238 for example, changing the system (i.e., calendar) time (governed by
 239 .BR CAP_SYS_TIME ),
 240 loading a kernel module (governed by
 241 .BR CAP_SYS_MODULE ),
 242 and creating a device (governed by
 243 .BR CAP_MKNOD ).
 244 Only a process with privileges in the
 245 .I initial
 246 user namespace can perform such operations.
 247 .PP
 248 Holding
 249 .B CAP_SYS_ADMIN
 250 within the user namespace that owns a process's mount namespace
 251 allows that process to create bind mounts
 252 and mount the following types of filesystems:
 253 .\" fs_flags = FS_USERNS_MOUNT in kernel sources
 254 .PP
 255 .RS 4
 256 .PD 0
 257 .IP * 2
 258 .IR /proc
 259 (since Linux 3.8)
 260 .IP *
 261 .IR /sys
 262 (since Linux 3.8)
 263 .IP *
 264 .IR devpts
 265 (since Linux 3.9)
 266 .IP *
 267 .BR tmpfs (5)
 268 (since Linux 3.9)
 269 .IP *
 270 .IR ramfs
 271 (since Linux 3.9)
 272 .IP *
 273 .IR mqueue
 274 (since Linux 3.9)
 275 .IP *
 276 .IR bpf
 277 .\" commit b2197755b2633e164a439682fb05a9b5ea48f706
 278 (since Linux 4.4)
 279 .IP *
 280 .IR overlayfs
 281 .\" commit 92dbc9dedccb9759c7f9f2f0ae6242396376988f
 282 .\" commit 4cb2c00c43b3fe88b32f29df4f76da1b92c33224
 283 (since Linux 5.11)
 284 .PD
 285 .RE
 286 .PP
 287 Holding
 288 .B CAP_SYS_ADMIN
 289 within the user namespace that owns a process's cgroup namespace
 290 allows (since Linux 4.6)
 291 that process to the mount the cgroup version 2 filesystem and
 292 cgroup version 1 named hierarchies
 293 (i.e., cgroup filesystems mounted with the
 294 .IR """none,name="""
 295 option).
 296 .PP
 297 Holding
 298 .B CAP_SYS_ADMIN
 299 within the user namespace that owns a process's PID namespace
 300 allows (since Linux 3.8)
 301 that process to mount
 302 .I /proc
 303 filesystems.
 304 .PP
 305 Note however, that mounting block-based filesystems can be done
 306 only by a process that holds
 307 .BR CAP_SYS_ADMIN
 308 in the initial user namespace.
 309 .\"
 310 .\" ============================================================
 311 .\"
 312 .SS Interaction of user namespaces and other types of namespaces
 313 Starting in Linux 3.8, unprivileged processes can create user namespaces,
 314 and the other types of namespaces can be created with just the
 315 .B CAP_SYS_ADMIN
 316 capability in the caller's user namespace.
 317 .PP
 318 When a nonuser namespace is created,
 319 it is owned by the user namespace in which the creating process
 320 was a member at the time of the creation of the namespace.
 321 Privileged operations on resources governed by the nonuser namespace
 322 require that the process has the necessary capabilities
 323 in the user namespace that owns the nonuser namespace.
 324 .PP
 325 If
 326 .BR CLONE_NEWUSER
 327 is specified along with other
 328 .B CLONE_NEW*
 329 flags in a single
 330 .BR clone (2)
 331 or
 332 .BR unshare (2)
 333 call, the user namespace is guaranteed to be created first,
 334 giving the child
 335 .RB ( clone (2))
 336 or caller
 337 .RB ( unshare (2))
 338 privileges over the remaining namespaces created by the call.
 339 Thus, it is possible for an unprivileged caller to specify this combination
 340 of flags.
 341 .PP
 342 When a new namespace (other than a user namespace) is created via
 343 .BR clone (2)
 344 or
 345 .BR unshare (2),
 346 the kernel records the user namespace of the creating process as the owner of
 347 the new namespace.
 348 (This association can't be changed.)
 349 When a process in the new namespace subsequently performs
 350 privileged operations that operate on global
 351 resources isolated by the namespace,
 352 the permission checks are performed according to the process's capabilities
 353 in the user namespace that the kernel associated with the new namespace.
 354 For example, suppose that a process attempts to change the hostname
 355 .RB ( sethostname (2)),
 356 a resource governed by the UTS namespace.
 357 In this case,
 358 the kernel will determine which user namespace owns
 359 the process's UTS namespace, and check whether the process has the
 360 required capability
 361 .RB ( CAP_SYS_ADMIN )
 362 in that user namespace.
 363 .PP
 364 The
 365 .BR NS_GET_USERNS
 366 .BR ioctl (2)
 367 operation can be used to discover the user namespace
 368 that owns a nonuser namespace; see
 369 .BR ioctl_ns (2).
 370 .\"
 371 .\" ============================================================
 372 .\"
 373 .SS User and group ID mappings: uid_map and gid_map
 374 When a user namespace is created,
 375 it starts out without a mapping of user IDs (group IDs)
 376 to the parent user namespace.
 377 The
 378 .IR /proc/[pid]/uid_map
 379 and
 380 .IR /proc/[pid]/gid_map
 381 files (available since Linux 3.5)
 382 .\" commit 22d917d80e842829d0ca0a561967d728eb1d6303
 383 expose the mappings for user and group IDs
 384 inside the user namespace for the process
 385 .IR pid .
 386 These files can be read to view the mappings in a user namespace and
 387 written to (once) to define the mappings.
 388 .PP
 389 The description in the following paragraphs explains the details for
 390 .IR uid_map ;
 391 .IR gid_map
 392 is exactly the same,
 393 but each instance of "user ID" is replaced by "group ID".
 394 .PP
 395 The
 396 .I uid_map
 397 file exposes the mapping of user IDs from the user namespace
 398 of the process
 399 .IR pid
 400 to the user namespace of the process that opened
 401 .IR uid_map
 402 (but see a qualification to this point below).
 403 In other words, processes that are in different user namespaces
 404 will potentially see different values when reading from a particular
 405 .I uid_map
 406 file, depending on the user ID mappings for the user namespaces
 407 of the reading processes.
 408 .PP
 409 Each line in the
 410 .I uid_map
 411 file specifies a 1-to-1 mapping of a range of contiguous
 412 user IDs between two user namespaces.
 413 (When a user namespace is first created, this file is empty.)
 414 The specification in each line takes the form of
 415 three numbers delimited by white space.
 416 The first two numbers specify the starting user ID in
 417 each of the two user namespaces.
 418 The third number specifies the length of the mapped range.
 419 In detail, the fields are interpreted as follows:
 420 .IP (1) 4
 421 The start of the range of user IDs in
 422 the user namespace of the process
 423 .IR pid .
 424 .IP (2)
 425 The start of the range of user
 426 IDs to which the user IDs specified by field one map.
 427 How field two is interpreted depends on whether the process that opened
 428 .I uid_map
 429 and the process
 430 .IR pid
 431 are in the same user namespace, as follows:
 432 .RS
 433 .IP a) 3
 434 If the two processes are in different user namespaces:
 435 field two is the start of a range of
 436 user IDs in the user namespace of the process that opened
 437 .IR uid_map .
 438 .IP b)
 439 If the two processes are in the same user namespace:
 440 field two is the start of the range of
 441 user IDs in the parent user namespace of the process
 442 .IR pid .
 443 This case enables the opener of
 444 .I uid_map
 445 (the common case here is opening
 446 .IR /proc/self/uid_map )
 447 to see the mapping of user IDs into the user namespace of the process
 448 that created this user namespace.
 449 .RE
 450 .IP (3)
 451 The length of the range of user IDs that is mapped between the two
 452 user namespaces.
 453 .PP
 454 System calls that return user IDs (group IDs)\(emfor example,
 455 .BR getuid (2),
 456 .BR getgid (2),
 457 and the credential fields in the structure returned by
 458 .BR stat (2)\(emreturn
 459 the user ID (group ID) mapped into the caller's user namespace.
 460 .PP
 461 When a process accesses a file, its user and group IDs
 462 are mapped into the initial user namespace for the purpose of permission
 463 checking and assigning IDs when creating a file.
 464 When a process retrieves file user and group IDs via
 465 .BR stat (2),
 466 the IDs are mapped in the opposite direction,
 467 to produce values relative to the process user and group ID mappings.
 468 .PP
 469 The initial user namespace has no parent namespace,
 470 but, for consistency, the kernel provides dummy user and group
 471 ID mapping files for this namespace.
 472 Looking at the
 473 .I uid_map
 474 file
 475 .RI ( gid_map
 476 is the same) from a shell in the initial namespace shows:
 477 .PP
 478 .in +4n
 479 .EX
 480 $ \fBcat /proc/$$/uid_map\fP
 481          0          0 4294967295
 482 .EE
 483 .in
 484 .PP
 485 This mapping tells us
 486 that the range starting at user ID 0 in this namespace
 487 maps to a range starting at 0 in the (nonexistent) parent namespace,
 488 and the length of the range is the largest 32-bit unsigned integer.
 489 This leaves 4294967295 (the 32-bit signed \-1 value) unmapped.
 490 This is deliberate:
 491 .IR "(uid_t)\ \-1"
 492 is used in several interfaces (e.g.,
 493 .BR setreuid (2))
 494 as a way to specify "no user ID".
 495 Leaving
 496 .IR "(uid_t)\ \-1"
 497 unmapped and unusable guarantees that there will be no
 498 confusion when using these interfaces.
 499 .\"
 500 .\" ============================================================
 501 .\"
 502 .SS Defining user and group ID mappings: writing to uid_map and gid_map
 503 After the creation of a new user namespace, the
 504 .I uid_map
 505 file of
 506 .I one
 507 of the processes in the namespace may be written to
 508 .I once
 509 to define the mapping of user IDs in the new user namespace.
 510 An attempt to write more than once to a
 511 .I uid_map
 512 file in a user namespace fails with the error
 513 .BR EPERM .
 514 Similar rules apply for
 515 .I gid_map
 516 files.
 517 .PP
 518 The lines written to
 519 .IR uid_map
 520 .RI ( gid_map )
 521 must conform to the following rules:
 522 .IP * 3
 523 The three fields must be valid numbers,
 524 and the last field must be greater than 0.
 525 .IP *
 526 Lines are terminated by newline characters.
 527 .IP *
 528 There is a limit on the number of lines in the file.
 529 In Linux 4.14 and earlier, this limit was (arbitrarily)
 530 .\" 5*12-byte records could fit in a 64B cache line
 531 set at 5 lines.
 532 Since Linux 4.15,
 533 .\" commit 6397fac4915ab3002dc15aae751455da1a852f25
 534 the limit is 340 lines.
 535 In addition, the number of bytes written to
 536 the file must be less than the system page size,
 537 and the write must be performed at the start of the file (i.e.,
 538 .BR lseek (2)
 539 and
 540 .BR pwrite (2)
 541 can't be used to write to nonzero offsets in the file).
 542 .IP *
 543 The range of user IDs (group IDs)
 544 specified in each line cannot overlap with the ranges
 545 in any other lines.
 546 In the initial implementation (Linux 3.8), this requirement was
 547 satisfied by a simplistic implementation that imposed the further
 548 requirement that
 549 the values in both field 1 and field 2 of successive lines must be
 550 in ascending numerical order,
 551 which prevented some otherwise valid maps from being created.
 552 Linux 3.9 and later
 553 .\" commit 0bd14b4fd72afd5df41e9fd59f356740f22fceba
 554 fix this limitation, allowing any valid set of nonoverlapping maps.
 555 .IP *
 556 At least one line must be written to the file.
 557 .PP
 558 Writes that violate the above rules fail with the error
 559 .BR EINVAL .
 560 .PP
 561 In order for a process to write to the
 562 .I /proc/[pid]/uid_map
 563 .RI ( /proc/[pid]/gid_map )
 564 file, all of the following requirements must be met:
 565 .IP 1. 3
 566 The writing process must have the
 567 .BR CAP_SETUID
 568 .RB ( CAP_SETGID )
 569 capability in the user namespace of the process
 570 .IR pid .
 571 .IP 2.
 572 The writing process must either be in the user namespace of the process
 573 .I pid
 574 or be in the parent user namespace of the process
 575 .IR pid .
 576 .IP 3.
 577 The mapped user IDs (group IDs) must in turn have a mapping
 578 in the parent user namespace.
 579 .IP 4.
 580 If updating
 581 .IR /proc/[pid]/uid_map
 582 to create a mapping that maps UID 0 in the parent namespace,
 583 then one of the following must be true:
 584 .RS
 585 .IP * 3
 586 if writing process is in the parent user namespace,
 587 then it must have the
 588 .BR CAP_SETFCAP
 589 capability in that user namespace; or
 590 .IP *
 591 if the writing process is in the child user namespace,
 592 then the process that created the user namespace must have had the
 593 .BR CAP_SETFCAP
 594 capability when the namespace was created.
 595 .RE
 596 .IP
 597 This rule has been in place since
 598 .\" commit db2e718a47984b9d71ed890eb2ea36ecf150de18
 599 Linux 5.12.
 600 It eliminates an earlier security bug whereby
 601 a UID 0 process that lacks the
 602 .B CAP_SETFCAP
 603 capability,
 604 which is needed to create a binary with namespaced file capabilities
 605 (as described in
 606 .BR capabilities (7)),
 607 could nevertheless create such a binary,
 608 by the following steps:
 609 .RS
 610 .IP * 3
 611 Create a new user namespace with the identity mapping
 612 (i.e., UID 0 in the new user namespace maps to UID 0 in the parent namespace),
 613 so that UID 0 in both namespaces is equivalent to the same root user ID.
 614 .IP *
 615 Since the child process has the
 616 .B CAP_SETFCAP
 617 capability, it could create a binary with namespaced file capabilities
 618 that would then be effective in the parent user namespace
 619 (because the root user IDs are the same in the two namespaces).
 620 .RE
 621 .IP 5.
 622 One of the following two cases applies:
 623 .RS
 624 .IP * 3
 625 .IR Either
 626 the writing process has the
 627 .BR CAP_SETUID
 628 .RB ( CAP_SETGID )
 629 capability in the
 630 .I parent
 631 user namespace.
 632 .RS
 633 .IP + 3
 634 No further restrictions apply:
 635 the process can make mappings to arbitrary user IDs (group IDs)
 636 in the parent user namespace.
 637 .RE
 638 .IP * 3
 639 .IR Or
 640 otherwise all of the following restrictions apply:
 641 .RS
 642 .IP + 3
 643 The data written to
 644 .I uid_map
 645 .RI ( gid_map )
 646 must consist of a single line that maps
 647 the writing process's effective user ID
 648 (group ID) in the parent user namespace to a user ID (group ID)
 649 in the user namespace.
 650 .IP +
 651 The writing process must have the same effective user ID as the process
 652 that created the user namespace.
 653 .IP +
 654 In the case of
 655 .IR gid_map ,
 656 use of the
 657 .BR setgroups (2)
 658 system call must first be denied by writing
 659 .RI \(dq deny \(dq
 660 to the
 661 .I /proc/[pid]/setgroups
 662 file (see below) before writing to
 663 .IR gid_map .
 664 .RE
 665 .RE
 666 .PP
 667 Writes that violate the above rules fail with the error
 668 .BR EPERM .
 669 .\"
 670 .\" ============================================================
 671 .\"
 672 .SS Interaction with system calls that change process UIDs or GIDs
 673 In a user namespace where the
 674 .I uid_map
 675 file has not been written, the system calls that change user IDs will fail.
 676 Similarly, if the
 677 .I gid_map
 678 file has not been written, the system calls that change group IDs will fail.
 679 After the
 680 .I uid_map
 681 and
 682 .I gid_map
 683 files have been written, only the mapped values may be used in
 684 system calls that change user and group IDs.
 685 .PP
 686 For user IDs, the relevant system calls include
 687 .BR setuid (2),
 688 .BR setfsuid (2),
 689 .BR setreuid (2),
 690 and
 691 .BR setresuid (2).
 692 For group IDs, the relevant system calls include
 693 .BR setgid (2),
 694 .BR setfsgid (2),
 695 .BR setregid (2),
 696 .BR setresgid (2),
 697 and
 698 .BR setgroups (2).
 699 .PP
 700 Writing
 701 .RI \(dq deny \(dq
 702 to the
 703 .I /proc/[pid]/setgroups
 704 file before writing to
 705 .I /proc/[pid]/gid_map
 706 .\" Things changed in Linux 3.19
 707 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
 708 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
 709 .\" http://lwn.net/Articles/626665/
 710 will permanently disable
 711 .BR setgroups (2)
 712 in a user namespace and allow writing to
 713 .I /proc/[pid]/gid_map
 714 without having the
 715 .BR CAP_SETGID
 716 capability in the parent user namespace.
 717 .\"
 718 .\" ============================================================
 719 .\"
 720 .SS The /proc/[pid]/setgroups file
 721 .\"
 722 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
 723 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
 724 .\" http://lwn.net/Articles/626665/
 725 .\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
 726 .\"
 727 The
 728 .I /proc/[pid]/setgroups
 729 file displays the string
 730 .RI \(dq allow \(dq
 731 if processes in the user namespace that contains the process
 732 .I pid
 733 are permitted to employ the
 734 .BR setgroups (2)
 735 system call; it displays
 736 .RI \(dq deny \(dq
 737 if
 738 .BR setgroups (2)
 739 is not permitted in that user namespace.
 740 Note that regardless of the value in the
 741 .I /proc/[pid]/setgroups
 742 file (and regardless of the process's capabilities), calls to
 743 .BR setgroups (2)
 744 are also not permitted if
 745 .IR /proc/[pid]/gid_map
 746 has not yet been set.
 747 .PP
 748 A privileged process (one with the
 749 .BR CAP_SYS_ADMIN
 750 capability in the namespace) may write either of the strings
 751 .RI \(dq allow \(dq
 752 or
 753 .RI \(dq deny \(dq
 754 to this file
 755 .I before
 756 writing a group ID mapping
 757 for this user namespace to the file
 758 .IR /proc/[pid]/gid_map .
 759 Writing the string
 760 .RI \(dq deny \(dq
 761 prevents any process in the user namespace from employing
 762 .BR setgroups (2).
 763 .PP
 764 The essence of the restrictions described in the preceding
 765 paragraph is that it is permitted to write to
 766 .I /proc/[pid]/setgroups
 767 only so long as calling
 768 .BR setgroups (2)
 769 is disallowed because
 770 .I /proc/[pid]/gid_map
 771 has not been set.
 772 This ensures that a process cannot transition from a state where
 773 .BR setgroups (2)
 774 is allowed to a state where
 775 .BR setgroups (2)
 776 is denied;
 777 a process can transition only from
 778 .BR setgroups (2)
 779 being disallowed to
 780 .BR setgroups (2)
 781 being allowed.
 782 .PP
 783 The default value of this file in the initial user namespace is
 784 .RI \(dq allow \(dq.
 785 .PP
 786 Once
 787 .IR /proc/[pid]/gid_map
 788 has been written to
 789 (which has the effect of enabling
 790 .BR setgroups (2)
 791 in the user namespace),
 792 it is no longer possible to disallow
 793 .BR setgroups (2)
 794 by writing
 795 .RI \(dq deny \(dq
 796 to
 797 .IR /proc/[pid]/setgroups
 798 (the write fails with the error
 799 .BR EPERM ).
 800 .PP
 801 A child user namespace inherits the
 802 .IR /proc/[pid]/setgroups
 803 setting from its parent.
 804 .PP
 805 If the
 806 .I setgroups
 807 file has the value
 808 .RI \(dq deny \(dq,
 809 then the
 810 .BR setgroups (2)
 811 system call can't subsequently be reenabled (by writing
 812 .RI \(dq allow \(dq
 813 to the file) in this user namespace.
 814 (Attempts to do so fail with the error
 815 .BR EPERM .)
 816 This restriction also propagates down to all child user namespaces of
 817 this user namespace.
 818 .PP
 819 The
 820 .I /proc/[pid]/setgroups
 821 file was added in Linux 3.19,
 822 but was backported to many earlier stable kernel series,
 823 because it addresses a security issue.
 824 The issue concerned files with permissions such as "rwx\-\-\-rwx".
 825 Such files give fewer permissions to "group" than they do to "other".
 826 This means that dropping groups using
 827 .BR setgroups (2)
 828 might allow a process file access that it did not formerly have.
 829 Before the existence of user namespaces this was not a concern,
 830 since only a privileged process (one with the
 831 .BR CAP_SETGID
 832 capability) could call
 833 .BR setgroups (2).
 834 However, with the introduction of user namespaces,
 835 it became possible for an unprivileged process to create
 836 a new namespace in which the user had all privileges.
 837 This then allowed formerly unprivileged
 838 users to drop groups and thus gain file access
 839 that they did not previously have.
 840 The
 841 .I /proc/[pid]/setgroups
 842 file was added to address this security issue,
 843 by denying any pathway for an unprivileged process to drop groups with
 844 .BR setgroups (2).
 845 .\"
 846 .\" /proc/PID/setgroups
 847 .\"     [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
 848 .\"     * Can write if have CAP_SYS_ADMIN in NS
 849 .\"     * Must write BEFORE writing to /proc/PID/gid_map
 850 .\"
 851 .\" setgroups()
 852 .\"     * Must already have written to gid_map
 853 .\"     * /proc/PID/setgroups must be "allow"
 854 .\"
 855 .\" /proc/PID/gid_map -- writing
 856 .\"     * Must already have written "deny" to /proc/PID/setgroups
 857 .\"
 858 .\" ============================================================
 859 .\"
 860 .SS Unmapped user and group IDs
 861 There are various places where an unmapped user ID (group ID)
 862 may be exposed to user space.
 863 For example, the first process in a new user namespace may call
 864 .BR getuid (2)
 865 before a user ID mapping has been defined for the namespace.
 866 In most such cases, an unmapped user ID is converted
 867 .\" from_kuid_munged(), from_kgid_munged()
 868 to the overflow user ID (group ID);
 869 the default value for the overflow user ID (group ID) is 65534.
 870 See the descriptions of
 871 .IR /proc/sys/kernel/overflowuid
 872 and
 873 .IR /proc/sys/kernel/overflowgid
 874 in
 875 .BR proc (5).
 876 .PP
 877 The cases where unmapped IDs are mapped in this fashion include
 878 system calls that return user IDs
 879 .RB ( getuid (2),
 880 .BR getgid (2),
 881 and similar),
 882 credentials passed over a UNIX domain socket,
 883 .\" also SO_PEERCRED
 884 credentials returned by
 885 .BR stat (2),
 886 .BR waitid (2),
 887 and the System V IPC "ctl"
 888 .B IPC_STAT
 889 operations,
 890 credentials exposed by
 891 .IR /proc/[pid]/status
 892 and the files in
 893 .IR /proc/sysvipc/* ,
 894 credentials returned via the
 895 .I si_uid
 896 field in the
 897 .I siginfo_t
 898 received with a signal (see
 899 .BR sigaction (2)),
 900 credentials written to the process accounting file (see
 901 .BR acct (5)),
 902 and credentials returned with POSIX message queue notifications (see
 903 .BR mq_notify (3)).
 904 .PP
 905 There is one notable case where unmapped user and group IDs are
 906 .I not
 907 .\" from_kuid(), from_kgid()
 908 .\" Also F_GETOWNER_UIDS is an exception
 909 converted to the corresponding overflow ID value.
 910 When viewing a
 911 .I uid_map
 912 or
 913 .I gid_map
 914 file in which there is no mapping for the second field,
 915 that field is displayed as 4294967295 (\-1 as an unsigned integer).
 916 .\"
 917 .\" ============================================================
 918 .\"
 919 .SS Accessing files
 920 In order to determine permissions when an unprivileged process accesses a file,
 921 the process credentials (UID, GID) and the file credentials
 922 are in effect mapped back to what they would be in
 923 the initial user namespace and then compared to determine
 924 the permissions that the process has on the file.
 925 The same is also of other objects that employ the credentials plus
 926 permissions mask accessibility model, such as System V IPC objects
 927 .\"
 928 .\" ============================================================
 929 .\"
 930 .SS Operation of file-related capabilities
 931 Certain capabilities allow a process to bypass various
 932 kernel-enforced restrictions when performing operations on
 933 files owned by other users or groups.
 934 These capabilities are:
 935 .BR CAP_CHOWN ,
 936 .BR CAP_DAC_OVERRIDE ,
 937 .BR CAP_DAC_READ_SEARCH ,
 938 .BR CAP_FOWNER ,
 939 and
 940 .BR CAP_FSETID .
 941 .PP
 942 Within a user namespace,
 943 these capabilities allow a process to bypass the rules
 944 if the process has the relevant capability over the file,
 945 meaning that:
 946 .IP * 3
 947 the process has the relevant effective capability in its user namespace; and
 948 .IP *
 949 the file's user ID and group ID both have valid mappings
 950 in the user namespace.
 951 .PP
 952 The
 953 .BR CAP_FOWNER
 954 capability is treated somewhat exceptionally:
 955 .\" These are the checks performed by the kernel function
 956 .\" inode_owner_or_capable(). There is one exception to the exception:
 957 .\" overriding the directory sticky permission bit requires that
 958 .\" the file has a valid mapping for both its UID and GID.
 959 it allows a process to bypass the corresponding rules so long as
 960 at least the file's user ID has a mapping in the user namespace
 961 (i.e., the file's group ID does not need to have a valid mapping).
 962 .\"
 963 .\" ============================================================
 964 .\"
 965 .SS Set-user-ID and set-group-ID programs
 966 When a process inside a user namespace executes
 967 a set-user-ID (set-group-ID) program,
 968 the process's effective user (group) ID inside the namespace is changed
 969 to whatever value is mapped for the user (group) ID of the file.
 970 However, if either the user
 971 .I or
 972 the group ID of the file has no mapping inside the namespace,
 973 the set-user-ID (set-group-ID) bit is silently ignored:
 974 the new program is executed,
 975 but the process's effective user (group) ID is left unchanged.
 976 (This mirrors the semantics of executing a set-user-ID or set-group-ID
 977 program that resides on a filesystem that was mounted with the
 978 .BR MS_NOSUID
 979 flag, as described in
 980 .BR mount (2).)
 981 .\"
 982 .\" ============================================================
 983 .\"
 984 .SS Miscellaneous
 985 When a process's user and group IDs are passed over a UNIX domain socket
 986 to a process in a different user namespace (see the description of
 987 .B SCM_CREDENTIALS
 988 in
 989 .BR unix (7)),
 990 they are translated into the corresponding values as per the
 991 receiving process's user and group ID mappings.
 992 .\"
 993 .SH CONFORMING TO
 994 Namespaces are a Linux-specific feature.
 995 .\"
 996 .SH NOTES
 997 Over the years, there have been a lot of features that have been added
 998 to the Linux kernel that have been made available only to privileged users
 999 because of their potential to confuse set-user-ID-root applications.
1000 In general, it becomes safe to allow the root user in a user namespace to
1001 use those features because it is impossible, while in a user namespace,
1002 to gain more privilege than the root user of a user namespace has.
1003 .\"
1004 .\" ============================================================
1005 .\"
1006 .SS Availability
1007 Use of user namespaces requires a kernel that is configured with the
1008 .B CONFIG_USER_NS
1009 option.
1010 User namespaces require support in a range of subsystems across
1011 the kernel.
1012 When an unsupported subsystem is configured into the kernel,
1013 it is not possible to configure user namespaces support.
1014 .PP
1015 As at Linux 3.8, most relevant subsystems supported user namespaces,
1016 but a number of filesystems did not have the infrastructure needed
1017 to map user and group IDs between user namespaces.
1018 Linux 3.9 added the required infrastructure support for many of
1019 the remaining unsupported filesystems
1020 (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
1021 Linux 3.12 added support for the last of the unsupported major filesystems,
1022 .\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
1023 XFS.
1024 .\"
1025 .SH EXAMPLES
1026 The program below is designed to allow experimenting with
1027 user namespaces, as well as other types of namespaces.
1028 It creates namespaces as specified by command-line options and then executes
1029 a command inside those namespaces.
1030 The comments and
1031 .I usage()
1032 function inside the program provide a full explanation of the program.
1033 The following shell session demonstrates its use.
1034 .PP
1035 First, we look at the run-time environment:
1036 .PP
1037 .in +4n
1038 .EX
1039 $ \fBuname \-rs\fP     # Need Linux 3.8 or later
1040 Linux 3.8.0
1041 $ \fBid \-u\fP         # Running as unprivileged user
1042 1000
1043 $ \fBid \-g\fP
1044 1000
1045 .EE
1046 .in
1047 .PP
1048 Now start a new shell in new user
1049 .RI ( \-U ),
1050 mount
1051 .RI ( \-m ),
1052 and PID
1053 .RI ( \-p )
1054 namespaces, with user ID
1055 .RI ( \-M )
1056 and group ID
1057 .RI ( \-G )
1058 1000 mapped to 0 inside the user namespace:
1059 .PP
1060 .in +4n
1061 .EX
1062 $ \fB./userns_child_exec \-p \-m \-U \-M \(aq0 1000 1\(aq \-G \(aq0 1000 1\(aq bash\fP
1063 .EE
1064 .in
1065 .PP
1066 The shell has PID 1, because it is the first process in the new
1067 PID namespace:
1068 .PP
1069 .in +4n
1070 .EX
1071 bash$ \fBecho $$\fP
1072 1
1073 .EE
1074 .in
1075 .PP
1076 Mounting a new
1077 .I /proc
1078 filesystem and listing all of the processes visible
1079 in the new PID namespace shows that the shell can't see
1080 any processes outside the PID namespace:
1081 .PP
1082 .in +4n
1083 .EX
1084 bash$ \fBmount \-t proc proc /proc\fP
1085 bash$ \fBps ax\fP
1086   PID TTY      STAT   TIME COMMAND
1087     1 pts/3    S      0:00 bash
1088    22 pts/3    R+     0:00 ps ax
1089 .EE
1090 .in
1091 .PP
1092 Inside the user namespace, the shell has user and group ID 0,
1093 and a full set of permitted and effective capabilities:
1094 .PP
1095 .in +4n
1096 .EX
1097 bash$ \fBcat /proc/$$/status | egrep \(aq\(ha[UG]id\(aq\fP
1098 Uid:    0       0       0       0
1099 Gid:    0       0       0       0
1100 bash$ \fBcat /proc/$$/status | egrep \(aq\(haCap(Prm|Inh|Eff)\(aq\fP
1101 CapInh: 0000000000000000
1102 CapPrm: 0000001fffffffff
1103 CapEff: 0000001fffffffff
1104 .EE
1105 .in
1106 .SS Program source
1107 \&
1108 .EX
1109 /* userns_child_exec.c
1110
1111    Licensed under GNU General Public License v2 or later
1112
1113    Create a child process that executes a shell command in new
1114    namespace(s); allow UID and GID mappings to be specified when
1115    creating a user namespace.
1116 */
1117 #define _GNU_SOURCE
1118 #include <sched.h>
1119 #include <unistd.h>
1120 #include <stdint.h>
1121 #include <stdlib.h>
1122 #include <sys/wait.h>
1123 #include <signal.h>
1124 #include <fcntl.h>
1125 #include <stdio.h>
1126 #include <string.h>
1127 #include <limits.h>
1128 #include <errno.h>
1129
1130 /* A simple error\-handling function: print an error message based
1131    on the value in \(aqerrno\(aq and terminate the calling process. */
1132
1133 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
1134                         } while (0)
1135
1136 struct child_args {
1137     char **argv;        /* Command to be executed by child, with args */
1138     int    pipe_fd[2];  /* Pipe used to synchronize parent and child */
1139 };
1140
1141 static int verbose;
1142
1143 static void
1144 usage(char *pname)
1145 {
1146     fprintf(stderr, "Usage: %s [options] cmd [arg...]\en\en", pname);
1147     fprintf(stderr, "Create a child process that executes a shell "
1148             "command in a new user namespace,\en"
1149             "and possibly also other new namespace(s).\en\en");
1150     fprintf(stderr, "Options can be:\en\en");
1151 #define fpe(str) fprintf(stderr, "    %s", str);
1152     fpe("\-i          New IPC namespace\en");
1153     fpe("\-m          New mount namespace\en");
1154     fpe("\-n          New network namespace\en");
1155     fpe("\-p          New PID namespace\en");
1156     fpe("\-u          New UTS namespace\en");
1157     fpe("\-U          New user namespace\en");
1158     fpe("\-M uid_map  Specify UID map for user namespace\en");
1159     fpe("\-G gid_map  Specify GID map for user namespace\en");
1160     fpe("\-z          Map user\(aqs UID and GID to 0 in user namespace\en");
1161     fpe("            (equivalent to: \-M \(aq0 <uid> 1\(aq \-G \(aq0 <gid> 1\(aq)\en");
1162     fpe("\-v          Display verbose messages\en");
1163     fpe("\en");
1164     fpe("If \-z, \-M, or \-G is specified, \-U is required.\en");
1165     fpe("It is not permitted to specify both \-z and either \-M or \-G.\en");
1166     fpe("\en");
1167     fpe("Map strings for \-M and \-G consist of records of the form:\en");
1168     fpe("\en");
1169     fpe("    ID\-inside\-ns   ID\-outside\-ns   len\en");
1170     fpe("\en");
1171     fpe("A map string can contain multiple records, separated"
1172         " by commas;\en");
1173     fpe("the commas are replaced by newlines before writing"
1174         " to map files.\en");
1175
1176     exit(EXIT_FAILURE);
1177 }
1178
1179 /* Update the mapping file \(aqmap_file\(aq, with the value provided in
1180    \(aqmapping\(aq, a string that defines a UID or GID mapping. A UID or
1181    GID mapping consists of one or more newline\-delimited records
1182    of the form:
1183
1184        ID_inside\-ns    ID\-outside\-ns   length
1185
1186    Requiring the user to supply a string that contains newlines is
1187    of course inconvenient for command\-line use. Thus, we permit the
1188    use of commas to delimit records in this string, and replace them
1189    with newlines before writing the string to the file. */
1190
1191 static void
1192 update_map(char *mapping, char *map_file)
1193 {
1194     int fd;
1195     size_t map_len;     /* Length of \(aqmapping\(aq */
1196
1197     /* Replace commas in mapping string with newlines. */
1198
1199     map_len = strlen(mapping);
1200     for (int j = 0; j < map_len; j++)
1201         if (mapping[j] == \(aq,\(aq)
1202             mapping[j] = \(aq\en\(aq;
1203
1204     fd = open(map_file, O_RDWR);
1205     if (fd == \-1) {
1206         fprintf(stderr, "ERROR: open %s: %s\en", map_file,
1207                 strerror(errno));
1208         exit(EXIT_FAILURE);
1209     }
1210
1211     if (write(fd, mapping, map_len) != map_len) {
1212         fprintf(stderr, "ERROR: write %s: %s\en", map_file,
1213                 strerror(errno));
1214         exit(EXIT_FAILURE);
1215     }
1216
1217     close(fd);
1218 }
1219
1220 /* Linux 3.19 made a change in the handling of setgroups(2) and the
1221    \(aqgid_map\(aq file to address a security issue. The issue allowed
1222    *unprivileged* users to employ user namespaces in order to drop
1223    The upshot of the 3.19 changes is that in order to update the
1224    \(aqgid_maps\(aq file, use of the setgroups() system call in this
1225    user namespace must first be disabled by writing "deny" to one of
1226    the /proc/PID/setgroups files for this namespace.  That is the
1227    purpose of the following function. */
1228
1229 static void
1230 proc_setgroups_write(pid_t child_pid, char *str)
1231 {
1232     char setgroups_path[PATH_MAX];
1233     int fd;
1234
1235     snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups",
1236             (intmax_t) child_pid);
1237
1238     fd = open(setgroups_path, O_RDWR);
1239     if (fd == \-1) {
1240
1241         /* We may be on a system that doesn\(aqt support
1242            /proc/PID/setgroups. In that case, the file won\(aqt exist,
1243            and the system won\(aqt impose the restrictions that Linux 3.19
1244            added. That\(aqs fine: we don\(aqt need to do anything in order
1245            to permit \(aqgid_map\(aq to be updated.
1246
1247            However, if the error from open() was something other than
1248            the ENOENT error that is expected for that case,  let the
1249            user know. */
1250
1251         if (errno != ENOENT)
1252             fprintf(stderr, "ERROR: open %s: %s\en", setgroups_path,
1253                 strerror(errno));
1254         return;
1255     }
1256
1257     if (write(fd, str, strlen(str)) == \-1)
1258         fprintf(stderr, "ERROR: write %s: %s\en", setgroups_path,
1259             strerror(errno));
1260
1261     close(fd);
1262 }
1263
1264 static int              /* Start function for cloned child */
1265 childFunc(void *arg)
1266 {
1267     struct child_args *args = arg;
1268     char ch;
1269
1270     /* Wait until the parent has updated the UID and GID mappings.
1271        See the comment in main(). We wait for end of file on a
1272        pipe that will be closed by the parent process once it has
1273        updated the mappings. */
1274
1275     close(args\->pipe_fd[1]);    /* Close our descriptor for the write
1276                                    end of the pipe so that we see EOF
1277                                    when parent closes its descriptor. */
1278     if (read(args\->pipe_fd[0], &ch, 1) != 0) {
1279         fprintf(stderr,
1280                 "Failure in child: read from pipe returned != 0\en");
1281         exit(EXIT_FAILURE);
1282     }
1283
1284     close(args\->pipe_fd[0]);
1285
1286     /* Execute a shell command. */
1287
1288     printf("About to exec %s\en", args\->argv[0]);
1289     execvp(args\->argv[0], args\->argv);
1290     errExit("execvp");
1291 }
1292
1293 #define STACK_SIZE (1024 * 1024)
1294
1295 static char child_stack[STACK_SIZE];    /* Space for child\(aqs stack */
1296
1297 int
1298 main(int argc, char *argv[])
1299 {
1300     int flags, opt, map_zero;
1301     pid_t child_pid;
1302     struct child_args args;
1303     char *uid_map, *gid_map;
1304     const int MAP_BUF_SIZE = 100;
1305     char map_buf[MAP_BUF_SIZE];
1306     char map_path[PATH_MAX];
1307
1308     /* Parse command\-line options. The initial \(aq+\(aq character in
1309        the final getopt() argument prevents GNU\-style permutation
1310        of command\-line options. That\(aqs useful, since sometimes
1311        the \(aqcommand\(aq to be executed by this program itself
1312        has command\-line options. We don\(aqt want getopt() to treat
1313        those as options to this program. */
1314
1315     flags = 0;
1316     verbose = 0;
1317     gid_map = NULL;
1318     uid_map = NULL;
1319     map_zero = 0;
1320     while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
1321         switch (opt) {
1322         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
1323         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
1324         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
1325         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
1326         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
1327         case \(aqv\(aq: verbose = 1;                  break;
1328         case \(aqz\(aq: map_zero = 1;                 break;
1329         case \(aqM\(aq: uid_map = optarg;             break;
1330         case \(aqG\(aq: gid_map = optarg;             break;
1331         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
1332         default:  usage(argv[0]);
1333         }
1334     }
1335
1336     /* \-M or \-G without \-U is nonsensical */
1337
1338     if (((uid_map != NULL || gid_map != NULL || map_zero) &&
1339                 !(flags & CLONE_NEWUSER)) ||
1340             (map_zero && (uid_map != NULL || gid_map != NULL)))
1341         usage(argv[0]);
1342
1343     args.argv = &argv[optind];
1344
1345     /* We use a pipe to synchronize the parent and child, in order to
1346        ensure that the parent sets the UID and GID maps before the child
1347        calls execve(). This ensures that the child maintains its
1348        capabilities during the execve() in the common case where we
1349        want to map the child\(aqs effective user ID to 0 in the new user
1350        namespace. Without this synchronization, the child would lose
1351        its capabilities if it performed an execve() with nonzero
1352        user IDs (see the capabilities(7) man page for details of the
1353        transformation of a process\(aqs capabilities during execve()). */
1354
1355     if (pipe(args.pipe_fd) == \-1)
1356         errExit("pipe");
1357
1358     /* Create the child in new namespace(s). */
1359
1360     child_pid = clone(childFunc, child_stack + STACK_SIZE,
1361                       flags | SIGCHLD, &args);
1362     if (child_pid == \-1)
1363         errExit("clone");
1364
1365     /* Parent falls through to here. */
1366
1367     if (verbose)
1368         printf("%s: PID of child created by clone() is %jd\en",
1369                 argv[0], (intmax_t) child_pid);
1370
1371     /* Update the UID and GID maps in the child. */
1372
1373     if (uid_map != NULL || map_zero) {
1374         snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map",
1375                 (intmax_t) child_pid);
1376         if (map_zero) {
1377             snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1",
1378                     (intmax_t) getuid());
1379             uid_map = map_buf;
1380         }
1381         update_map(uid_map, map_path);
1382     }
1383
1384     if (gid_map != NULL || map_zero) {
1385         proc_setgroups_write(child_pid, "deny");
1386
1387         snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map",
1388                 (intmax_t) child_pid);
1389         if (map_zero) {
1390             snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1",
1391                     (intmax_t) getgid());
1392             gid_map = map_buf;
1393         }
1394         update_map(gid_map, map_path);
1395     }
1396
1397     /* Close the write end of the pipe, to signal to the child that we
1398        have updated the UID and GID maps. */
1399
1400     close(args.pipe_fd[1]);
1401
1402     if (waitpid(child_pid, NULL, 0) == \-1)      /* Wait for child */
1403         errExit("waitpid");
1404
1405     if (verbose)
1406         printf("%s: terminating\en", argv[0]);
1407
1408     exit(EXIT_SUCCESS);
1409 }
1410 .EE
1411 .SH SEE ALSO
1412 .BR newgidmap (1),      \" From the shadow package
1413 .BR newuidmap (1),      \" From the shadow package
1414 .BR clone (2),
1415 .BR ptrace (2),
1416 .BR setns (2),
1417 .BR unshare (2),
1418 .BR proc (5),
1419 .BR subgid (5),         \" From the shadow package
1420 .BR subuid (5),         \" From the shadow package
1421 .BR capabilities (7),
1422 .BR cgroup_namespaces (7),
1423 .BR credentials (7),
1424 .BR namespaces (7),
1425 .BR pid_namespaces (7)
1426 .PP
1427 The kernel source file
1428 .IR Documentation/admin\-guide/namespaces/resource\-control.rst .