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 One of the following two cases applies:
 581 .RS
 582 .IP * 3
 583 .IR Either
 584 the writing process has the
 585 .BR CAP_SETUID
 586 .RB ( CAP_SETGID )
 587 capability in the
 588 .I parent
 589 user namespace.
 590 .RS
 591 .IP + 3
 592 No further restrictions apply:
 593 the process can make mappings to arbitrary user IDs (group IDs)
 594 in the parent user namespace.
 595 .RE
 596 .IP * 3
 597 .IR Or
 598 otherwise all of the following restrictions apply:
 599 .RS
 600 .IP + 3
 601 The data written to
 602 .I uid_map
 603 .RI ( gid_map )
 604 must consist of a single line that maps
 605 the writing process's effective user ID
 606 (group ID) in the parent user namespace to a user ID (group ID)
 607 in the user namespace.
 608 .IP +
 609 The writing process must have the same effective user ID as the process
 610 that created the user namespace.
 611 .IP +
 612 In the case of
 613 .IR gid_map ,
 614 use of the
 615 .BR setgroups (2)
 616 system call must first be denied by writing
 617 .RI \(dq deny \(dq
 618 to the
 619 .I /proc/[pid]/setgroups
 620 file (see below) before writing to
 621 .IR gid_map .
 622 .RE
 623 .RE
 624 .PP
 625 Writes that violate the above rules fail with the error
 626 .BR EPERM .
 627 .\"
 628 .\" ============================================================
 629 .\"
 630 .SS Interaction with system calls that change process UIDs or GIDs
 631 In a user namespace where the
 632 .I uid_map
 633 file has not been written, the system calls that change user IDs will fail.
 634 Similarly, if the
 635 .I gid_map
 636 file has not been written, the system calls that change group IDs will fail.
 637 After the
 638 .I uid_map
 639 and
 640 .I gid_map
 641 files have been written, only the mapped values may be used in
 642 system calls that change user and group IDs.
 643 .PP
 644 For user IDs, the relevant system calls include
 645 .BR setuid (2),
 646 .BR setfsuid (2),
 647 .BR setreuid (2),
 648 and
 649 .BR setresuid (2).
 650 For group IDs, the relevant system calls include
 651 .BR setgid (2),
 652 .BR setfsgid (2),
 653 .BR setregid (2),
 654 .BR setresgid (2),
 655 and
 656 .BR setgroups (2).
 657 .PP
 658 Writing
 659 .RI \(dq deny \(dq
 660 to the
 661 .I /proc/[pid]/setgroups
 662 file before writing to
 663 .I /proc/[pid]/gid_map
 664 .\" Things changed in Linux 3.19
 665 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
 666 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
 667 .\" http://lwn.net/Articles/626665/
 668 will permanently disable
 669 .BR setgroups (2)
 670 in a user namespace and allow writing to
 671 .I /proc/[pid]/gid_map
 672 without having the
 673 .BR CAP_SETGID
 674 capability in the parent user namespace.
 675 .\"
 676 .\" ============================================================
 677 .\"
 678 .SS The /proc/[pid]/setgroups file
 679 .\"
 680 .\" commit 9cc46516ddf497ea16e8d7cb986ae03a0f6b92f8
 681 .\" commit 66d2f338ee4c449396b6f99f5e75cd18eb6df272
 682 .\" http://lwn.net/Articles/626665/
 683 .\" http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2014-8989
 684 .\"
 685 The
 686 .I /proc/[pid]/setgroups
 687 file displays the string
 688 .RI \(dq allow \(dq
 689 if processes in the user namespace that contains the process
 690 .I pid
 691 are permitted to employ the
 692 .BR setgroups (2)
 693 system call; it displays
 694 .RI \(dq deny \(dq
 695 if
 696 .BR setgroups (2)
 697 is not permitted in that user namespace.
 698 Note that regardless of the value in the
 699 .I /proc/[pid]/setgroups
 700 file (and regardless of the process's capabilities), calls to
 701 .BR setgroups (2)
 702 are also not permitted if
 703 .IR /proc/[pid]/gid_map
 704 has not yet been set.
 705 .PP
 706 A privileged process (one with the
 707 .BR CAP_SYS_ADMIN
 708 capability in the namespace) may write either of the strings
 709 .RI \(dq allow \(dq
 710 or
 711 .RI \(dq deny \(dq
 712 to this file
 713 .I before
 714 writing a group ID mapping
 715 for this user namespace to the file
 716 .IR /proc/[pid]/gid_map .
 717 Writing the string
 718 .RI \(dq deny \(dq
 719 prevents any process in the user namespace from employing
 720 .BR setgroups (2).
 721 .PP
 722 The essence of the restrictions described in the preceding
 723 paragraph is that it is permitted to write to
 724 .I /proc/[pid]/setgroups
 725 only so long as calling
 726 .BR setgroups (2)
 727 is disallowed because
 728 .I /proc/[pid]/gid_map
 729 has not been set.
 730 This ensures that a process cannot transition from a state where
 731 .BR setgroups (2)
 732 is allowed to a state where
 733 .BR setgroups (2)
 734 is denied;
 735 a process can transition only from
 736 .BR setgroups (2)
 737 being disallowed to
 738 .BR setgroups (2)
 739 being allowed.
 740 .PP
 741 The default value of this file in the initial user namespace is
 742 .RI \(dq allow \(dq.
 743 .PP
 744 Once
 745 .IR /proc/[pid]/gid_map
 746 has been written to
 747 (which has the effect of enabling
 748 .BR setgroups (2)
 749 in the user namespace),
 750 it is no longer possible to disallow
 751 .BR setgroups (2)
 752 by writing
 753 .RI \(dq deny \(dq
 754 to
 755 .IR /proc/[pid]/setgroups
 756 (the write fails with the error
 757 .BR EPERM ).
 758 .PP
 759 A child user namespace inherits the
 760 .IR /proc/[pid]/setgroups
 761 setting from its parent.
 762 .PP
 763 If the
 764 .I setgroups
 765 file has the value
 766 .RI \(dq deny \(dq,
 767 then the
 768 .BR setgroups (2)
 769 system call can't subsequently be reenabled (by writing
 770 .RI \(dq allow \(dq
 771 to the file) in this user namespace.
 772 (Attempts to do so fail with the error
 773 .BR EPERM .)
 774 This restriction also propagates down to all child user namespaces of
 775 this user namespace.
 776 .PP
 777 The
 778 .I /proc/[pid]/setgroups
 779 file was added in Linux 3.19,
 780 but was backported to many earlier stable kernel series,
 781 because it addresses a security issue.
 782 The issue concerned files with permissions such as "rwx\-\-\-rwx".
 783 Such files give fewer permissions to "group" than they do to "other".
 784 This means that dropping groups using
 785 .BR setgroups (2)
 786 might allow a process file access that it did not formerly have.
 787 Before the existence of user namespaces this was not a concern,
 788 since only a privileged process (one with the
 789 .BR CAP_SETGID
 790 capability) could call
 791 .BR setgroups (2).
 792 However, with the introduction of user namespaces,
 793 it became possible for an unprivileged process to create
 794 a new namespace in which the user had all privileges.
 795 This then allowed formerly unprivileged
 796 users to drop groups and thus gain file access
 797 that they did not previously have.
 798 The
 799 .I /proc/[pid]/setgroups
 800 file was added to address this security issue,
 801 by denying any pathway for an unprivileged process to drop groups with
 802 .BR setgroups (2).
 803 .\"
 804 .\" /proc/PID/setgroups
 805 .\"     [allow == setgroups() is allowed, "deny" == setgroups() is disallowed]
 806 .\"     * Can write if have CAP_SYS_ADMIN in NS
 807 .\"     * Must write BEFORE writing to /proc/PID/gid_map
 808 .\"
 809 .\" setgroups()
 810 .\"     * Must already have written to gid_map
 811 .\"     * /proc/PID/setgroups must be "allow"
 812 .\"
 813 .\" /proc/PID/gid_map -- writing
 814 .\"     * Must already have written "deny" to /proc/PID/setgroups
 815 .\"
 816 .\" ============================================================
 817 .\"
 818 .SS Unmapped user and group IDs
 819 There are various places where an unmapped user ID (group ID)
 820 may be exposed to user space.
 821 For example, the first process in a new user namespace may call
 822 .BR getuid (2)
 823 before a user ID mapping has been defined for the namespace.
 824 In most such cases, an unmapped user ID is converted
 825 .\" from_kuid_munged(), from_kgid_munged()
 826 to the overflow user ID (group ID);
 827 the default value for the overflow user ID (group ID) is 65534.
 828 See the descriptions of
 829 .IR /proc/sys/kernel/overflowuid
 830 and
 831 .IR /proc/sys/kernel/overflowgid
 832 in
 833 .BR proc (5).
 834 .PP
 835 The cases where unmapped IDs are mapped in this fashion include
 836 system calls that return user IDs
 837 .RB ( getuid (2),
 838 .BR getgid (2),
 839 and similar),
 840 credentials passed over a UNIX domain socket,
 841 .\" also SO_PEERCRED
 842 credentials returned by
 843 .BR stat (2),
 844 .BR waitid (2),
 845 and the System V IPC "ctl"
 846 .B IPC_STAT
 847 operations,
 848 credentials exposed by
 849 .IR /proc/[pid]/status
 850 and the files in
 851 .IR /proc/sysvipc/* ,
 852 credentials returned via the
 853 .I si_uid
 854 field in the
 855 .I siginfo_t
 856 received with a signal (see
 857 .BR sigaction (2)),
 858 credentials written to the process accounting file (see
 859 .BR acct (5)),
 860 and credentials returned with POSIX message queue notifications (see
 861 .BR mq_notify (3)).
 862 .PP
 863 There is one notable case where unmapped user and group IDs are
 864 .I not
 865 .\" from_kuid(), from_kgid()
 866 .\" Also F_GETOWNER_UIDS is an exception
 867 converted to the corresponding overflow ID value.
 868 When viewing a
 869 .I uid_map
 870 or
 871 .I gid_map
 872 file in which there is no mapping for the second field,
 873 that field is displayed as 4294967295 (\-1 as an unsigned integer).
 874 .\"
 875 .\" ============================================================
 876 .\"
 877 .SS Accessing files
 878 In order to determine permissions when an unprivileged process accesses a file,
 879 the process credentials (UID, GID) and the file credentials
 880 are in effect mapped back to what they would be in
 881 the initial user namespace and then compared to determine
 882 the permissions that the process has on the file.
 883 The same is also of other objects that employ the credentials plus
 884 permissions mask accessibility model, such as System V IPC objects
 885 .\"
 886 .\" ============================================================
 887 .\"
 888 .SS Operation of file-related capabilities
 889 Certain capabilities allow a process to bypass various
 890 kernel-enforced restrictions when performing operations on
 891 files owned by other users or groups.
 892 These capabilities are:
 893 .BR CAP_CHOWN ,
 894 .BR CAP_DAC_OVERRIDE ,
 895 .BR CAP_DAC_READ_SEARCH ,
 896 .BR CAP_FOWNER ,
 897 and
 898 .BR CAP_FSETID .
 899 .PP
 900 Within a user namespace,
 901 these capabilities allow a process to bypass the rules
 902 if the process has the relevant capability over the file,
 903 meaning that:
 904 .IP * 3
 905 the process has the relevant effective capability in its user namespace; and
 906 .IP *
 907 the file's user ID and group ID both have valid mappings
 908 in the user namespace.
 909 .PP
 910 The
 911 .BR CAP_FOWNER
 912 capability is treated somewhat exceptionally:
 913 .\" These are the checks performed by the kernel function
 914 .\" inode_owner_or_capable(). There is one exception to the exception:
 915 .\" overriding the directory sticky permission bit requires that
 916 .\" the file has a valid mapping for both its UID and GID.
 917 it allows a process to bypass the corresponding rules so long as
 918 at least the file's user ID has a mapping in the user namespace
 919 (i.e., the file's group ID does not need to have a valid mapping).
 920 .\"
 921 .\" ============================================================
 922 .\"
 923 .SS Set-user-ID and set-group-ID programs
 924 When a process inside a user namespace executes
 925 a set-user-ID (set-group-ID) program,
 926 the process's effective user (group) ID inside the namespace is changed
 927 to whatever value is mapped for the user (group) ID of the file.
 928 However, if either the user
 929 .I or
 930 the group ID of the file has no mapping inside the namespace,
 931 the set-user-ID (set-group-ID) bit is silently ignored:
 932 the new program is executed,
 933 but the process's effective user (group) ID is left unchanged.
 934 (This mirrors the semantics of executing a set-user-ID or set-group-ID
 935 program that resides on a filesystem that was mounted with the
 936 .BR MS_NOSUID
 937 flag, as described in
 938 .BR mount (2).)
 939 .\"
 940 .\" ============================================================
 941 .\"
 942 .SS Miscellaneous
 943 When a process's user and group IDs are passed over a UNIX domain socket
 944 to a process in a different user namespace (see the description of
 945 .B SCM_CREDENTIALS
 946 in
 947 .BR unix (7)),
 948 they are translated into the corresponding values as per the
 949 receiving process's user and group ID mappings.
 950 .\"
 951 .SH CONFORMING TO
 952 Namespaces are a Linux-specific feature.
 953 .\"
 954 .SH NOTES
 955 Over the years, there have been a lot of features that have been added
 956 to the Linux kernel that have been made available only to privileged users
 957 because of their potential to confuse set-user-ID-root applications.
 958 In general, it becomes safe to allow the root user in a user namespace to
 959 use those features because it is impossible, while in a user namespace,
 960 to gain more privilege than the root user of a user namespace has.
 961 .\"
 962 .\" ============================================================
 963 .\"
 964 .SS Availability
 965 Use of user namespaces requires a kernel that is configured with the
 966 .B CONFIG_USER_NS
 967 option.
 968 User namespaces require support in a range of subsystems across
 969 the kernel.
 970 When an unsupported subsystem is configured into the kernel,
 971 it is not possible to configure user namespaces support.
 972 .PP
 973 As at Linux 3.8, most relevant subsystems supported user namespaces,
 974 but a number of filesystems did not have the infrastructure needed
 975 to map user and group IDs between user namespaces.
 976 Linux 3.9 added the required infrastructure support for many of
 977 the remaining unsupported filesystems
 978 (Plan 9 (9P), Andrew File System (AFS), Ceph, CIFS, CODA, NFS, and OCFS2).
 979 Linux 3.12 added support for the last of the unsupported major filesystems,
 980 .\" commit d6970d4b726cea6d7a9bc4120814f95c09571fc3
 981 XFS.
 982 .\"
 983 .SH EXAMPLES
 984 The program below is designed to allow experimenting with
 985 user namespaces, as well as other types of namespaces.
 986 It creates namespaces as specified by command-line options and then executes
 987 a command inside those namespaces.
 988 The comments and
 989 .I usage()
 990 function inside the program provide a full explanation of the program.
 991 The following shell session demonstrates its use.
 992 .PP
 993 First, we look at the run-time environment:
 994 .PP
 995 .in +4n
 996 .EX
 997 $ \fBuname \-rs\fP     # Need Linux 3.8 or later
 998 Linux 3.8.0
 999 $ \fBid \-u\fP         # Running as unprivileged user
1000 1000
1001 $ \fBid \-g\fP
1002 1000
1003 .EE
1004 .in
1005 .PP
1006 Now start a new shell in new user
1007 .RI ( \-U ),
1008 mount
1009 .RI ( \-m ),
1010 and PID
1011 .RI ( \-p )
1012 namespaces, with user ID
1013 .RI ( \-M )
1014 and group ID
1015 .RI ( \-G )
1016 1000 mapped to 0 inside the user namespace:
1017 .PP
1018 .in +4n
1019 .EX
1020 $ \fB./userns_child_exec \-p \-m \-U \-M \(aq0 1000 1\(aq \-G \(aq0 1000 1\(aq bash\fP
1021 .EE
1022 .in
1023 .PP
1024 The shell has PID 1, because it is the first process in the new
1025 PID namespace:
1026 .PP
1027 .in +4n
1028 .EX
1029 bash$ \fBecho $$\fP
1030 1
1031 .EE
1032 .in
1033 .PP
1034 Mounting a new
1035 .I /proc
1036 filesystem and listing all of the processes visible
1037 in the new PID namespace shows that the shell can't see
1038 any processes outside the PID namespace:
1039 .PP
1040 .in +4n
1041 .EX
1042 bash$ \fBmount \-t proc proc /proc\fP
1043 bash$ \fBps ax\fP
1044   PID TTY      STAT   TIME COMMAND
1045     1 pts/3    S      0:00 bash
1046    22 pts/3    R+     0:00 ps ax
1047 .EE
1048 .in
1049 .PP
1050 Inside the user namespace, the shell has user and group ID 0,
1051 and a full set of permitted and effective capabilities:
1052 .PP
1053 .in +4n
1054 .EX
1055 bash$ \fBcat /proc/$$/status | egrep \(aq\(ha[UG]id\(aq\fP
1056 Uid:    0       0       0       0
1057 Gid:    0       0       0       0
1058 bash$ \fBcat /proc/$$/status | egrep \(aq\(haCap(Prm|Inh|Eff)\(aq\fP
1059 CapInh: 0000000000000000
1060 CapPrm: 0000001fffffffff
1061 CapEff: 0000001fffffffff
1062 .EE
1063 .in
1064 .SS Program source
1065 \&
1066 .EX
1067 /* userns_child_exec.c
1068
1069    Licensed under GNU General Public License v2 or later
1070
1071    Create a child process that executes a shell command in new
1072    namespace(s); allow UID and GID mappings to be specified when
1073    creating a user namespace.
1074 */
1075 #define _GNU_SOURCE
1076 #include <sched.h>
1077 #include <unistd.h>
1078 #include <stdint.h>
1079 #include <stdlib.h>
1080 #include <sys/wait.h>
1081 #include <signal.h>
1082 #include <fcntl.h>
1083 #include <stdio.h>
1084 #include <string.h>
1085 #include <limits.h>
1086 #include <errno.h>
1087
1088 /* A simple error\-handling function: print an error message based
1089    on the value in \(aqerrno\(aq and terminate the calling process. */
1090
1091 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
1092                         } while (0)
1093
1094 struct child_args {
1095     char **argv;        /* Command to be executed by child, with args */
1096     int    pipe_fd[2];  /* Pipe used to synchronize parent and child */
1097 };
1098
1099 static int verbose;
1100
1101 static void
1102 usage(char *pname)
1103 {
1104     fprintf(stderr, "Usage: %s [options] cmd [arg...]\en\en", pname);
1105     fprintf(stderr, "Create a child process that executes a shell "
1106             "command in a new user namespace,\en"
1107             "and possibly also other new namespace(s).\en\en");
1108     fprintf(stderr, "Options can be:\en\en");
1109 #define fpe(str) fprintf(stderr, "    %s", str);
1110     fpe("\-i          New IPC namespace\en");
1111     fpe("\-m          New mount namespace\en");
1112     fpe("\-n          New network namespace\en");
1113     fpe("\-p          New PID namespace\en");
1114     fpe("\-u          New UTS namespace\en");
1115     fpe("\-U          New user namespace\en");
1116     fpe("\-M uid_map  Specify UID map for user namespace\en");
1117     fpe("\-G gid_map  Specify GID map for user namespace\en");
1118     fpe("\-z          Map user\(aqs UID and GID to 0 in user namespace\en");
1119     fpe("            (equivalent to: \-M \(aq0 <uid> 1\(aq \-G \(aq0 <gid> 1\(aq)\en");
1120     fpe("\-v          Display verbose messages\en");
1121     fpe("\en");
1122     fpe("If \-z, \-M, or \-G is specified, \-U is required.\en");
1123     fpe("It is not permitted to specify both \-z and either \-M or \-G.\en");
1124     fpe("\en");
1125     fpe("Map strings for \-M and \-G consist of records of the form:\en");
1126     fpe("\en");
1127     fpe("    ID\-inside\-ns   ID\-outside\-ns   len\en");
1128     fpe("\en");
1129     fpe("A map string can contain multiple records, separated"
1130         " by commas;\en");
1131     fpe("the commas are replaced by newlines before writing"
1132         " to map files.\en");
1133
1134     exit(EXIT_FAILURE);
1135 }
1136
1137 /* Update the mapping file \(aqmap_file\(aq, with the value provided in
1138    \(aqmapping\(aq, a string that defines a UID or GID mapping. A UID or
1139    GID mapping consists of one or more newline\-delimited records
1140    of the form:
1141
1142        ID_inside\-ns    ID\-outside\-ns   length
1143
1144    Requiring the user to supply a string that contains newlines is
1145    of course inconvenient for command\-line use. Thus, we permit the
1146    use of commas to delimit records in this string, and replace them
1147    with newlines before writing the string to the file. */
1148
1149 static void
1150 update_map(char *mapping, char *map_file)
1151 {
1152     int fd;
1153     size_t map_len;     /* Length of \(aqmapping\(aq */
1154
1155     /* Replace commas in mapping string with newlines. */
1156
1157     map_len = strlen(mapping);
1158     for (int j = 0; j < map_len; j++)
1159         if (mapping[j] == \(aq,\(aq)
1160             mapping[j] = \(aq\en\(aq;
1161
1162     fd = open(map_file, O_RDWR);
1163     if (fd == \-1) {
1164         fprintf(stderr, "ERROR: open %s: %s\en", map_file,
1165                 strerror(errno));
1166         exit(EXIT_FAILURE);
1167     }
1168
1169     if (write(fd, mapping, map_len) != map_len) {
1170         fprintf(stderr, "ERROR: write %s: %s\en", map_file,
1171                 strerror(errno));
1172         exit(EXIT_FAILURE);
1173     }
1174
1175     close(fd);
1176 }
1177
1178 /* Linux 3.19 made a change in the handling of setgroups(2) and the
1179    \(aqgid_map\(aq file to address a security issue. The issue allowed
1180    *unprivileged* users to employ user namespaces in order to drop
1181    The upshot of the 3.19 changes is that in order to update the
1182    \(aqgid_maps\(aq file, use of the setgroups() system call in this
1183    user namespace must first be disabled by writing "deny" to one of
1184    the /proc/PID/setgroups files for this namespace.  That is the
1185    purpose of the following function. */
1186
1187 static void
1188 proc_setgroups_write(pid_t child_pid, char *str)
1189 {
1190     char setgroups_path[PATH_MAX];
1191     int fd;
1192
1193     snprintf(setgroups_path, PATH_MAX, "/proc/%jd/setgroups",
1194             (intmax_t) child_pid);
1195
1196     fd = open(setgroups_path, O_RDWR);
1197     if (fd == \-1) {
1198
1199         /* We may be on a system that doesn\(aqt support
1200            /proc/PID/setgroups. In that case, the file won\(aqt exist,
1201            and the system won\(aqt impose the restrictions that Linux 3.19
1202            added. That\(aqs fine: we don\(aqt need to do anything in order
1203            to permit \(aqgid_map\(aq to be updated.
1204
1205            However, if the error from open() was something other than
1206            the ENOENT error that is expected for that case,  let the
1207            user know. */
1208
1209         if (errno != ENOENT)
1210             fprintf(stderr, "ERROR: open %s: %s\en", setgroups_path,
1211                 strerror(errno));
1212         return;
1213     }
1214
1215     if (write(fd, str, strlen(str)) == \-1)
1216         fprintf(stderr, "ERROR: write %s: %s\en", setgroups_path,
1217             strerror(errno));
1218
1219     close(fd);
1220 }
1221
1222 static int              /* Start function for cloned child */
1223 childFunc(void *arg)
1224 {
1225     struct child_args *args = arg;
1226     char ch;
1227
1228     /* Wait until the parent has updated the UID and GID mappings.
1229        See the comment in main(). We wait for end of file on a
1230        pipe that will be closed by the parent process once it has
1231        updated the mappings. */
1232
1233     close(args\->pipe_fd[1]);    /* Close our descriptor for the write
1234                                    end of the pipe so that we see EOF
1235                                    when parent closes its descriptor. */
1236     if (read(args\->pipe_fd[0], &ch, 1) != 0) {
1237         fprintf(stderr,
1238                 "Failure in child: read from pipe returned != 0\en");
1239         exit(EXIT_FAILURE);
1240     }
1241
1242     close(args\->pipe_fd[0]);
1243
1244     /* Execute a shell command. */
1245
1246     printf("About to exec %s\en", args\->argv[0]);
1247     execvp(args\->argv[0], args\->argv);
1248     errExit("execvp");
1249 }
1250
1251 #define STACK_SIZE (1024 * 1024)
1252
1253 static char child_stack[STACK_SIZE];    /* Space for child\(aqs stack */
1254
1255 int
1256 main(int argc, char *argv[])
1257 {
1258     int flags, opt, map_zero;
1259     pid_t child_pid;
1260     struct child_args args;
1261     char *uid_map, *gid_map;
1262     const int MAP_BUF_SIZE = 100;
1263     char map_buf[MAP_BUF_SIZE];
1264     char map_path[PATH_MAX];
1265
1266     /* Parse command\-line options. The initial \(aq+\(aq character in
1267        the final getopt() argument prevents GNU\-style permutation
1268        of command\-line options. That\(aqs useful, since sometimes
1269        the \(aqcommand\(aq to be executed by this program itself
1270        has command\-line options. We don\(aqt want getopt() to treat
1271        those as options to this program. */
1272
1273     flags = 0;
1274     verbose = 0;
1275     gid_map = NULL;
1276     uid_map = NULL;
1277     map_zero = 0;
1278     while ((opt = getopt(argc, argv, "+imnpuUM:G:zv")) != \-1) {
1279         switch (opt) {
1280         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
1281         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
1282         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
1283         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
1284         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
1285         case \(aqv\(aq: verbose = 1;                  break;
1286         case \(aqz\(aq: map_zero = 1;                 break;
1287         case \(aqM\(aq: uid_map = optarg;             break;
1288         case \(aqG\(aq: gid_map = optarg;             break;
1289         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
1290         default:  usage(argv[0]);
1291         }
1292     }
1293
1294     /* \-M or \-G without \-U is nonsensical */
1295
1296     if (((uid_map != NULL || gid_map != NULL || map_zero) &&
1297                 !(flags & CLONE_NEWUSER)) ||
1298             (map_zero && (uid_map != NULL || gid_map != NULL)))
1299         usage(argv[0]);
1300
1301     args.argv = &argv[optind];
1302
1303     /* We use a pipe to synchronize the parent and child, in order to
1304        ensure that the parent sets the UID and GID maps before the child
1305        calls execve(). This ensures that the child maintains its
1306        capabilities during the execve() in the common case where we
1307        want to map the child\(aqs effective user ID to 0 in the new user
1308        namespace. Without this synchronization, the child would lose
1309        its capabilities if it performed an execve() with nonzero
1310        user IDs (see the capabilities(7) man page for details of the
1311        transformation of a process\(aqs capabilities during execve()). */
1312
1313     if (pipe(args.pipe_fd) == \-1)
1314         errExit("pipe");
1315
1316     /* Create the child in new namespace(s). */
1317
1318     child_pid = clone(childFunc, child_stack + STACK_SIZE,
1319                       flags | SIGCHLD, &args);
1320     if (child_pid == \-1)
1321         errExit("clone");
1322
1323     /* Parent falls through to here. */
1324
1325     if (verbose)
1326         printf("%s: PID of child created by clone() is %jd\en",
1327                 argv[0], (intmax_t) child_pid);
1328
1329     /* Update the UID and GID maps in the child. */
1330
1331     if (uid_map != NULL || map_zero) {
1332         snprintf(map_path, PATH_MAX, "/proc/%jd/uid_map",
1333                 (intmax_t) child_pid);
1334         if (map_zero) {
1335             snprintf(map_buf, MAP_BUF_SIZE, "0 %jd 1",
1336                     (intmax_t) getuid());
1337             uid_map = map_buf;
1338         }
1339         update_map(uid_map, map_path);
1340     }
1341
1342     if (gid_map != NULL || map_zero) {
1343         proc_setgroups_write(child_pid, "deny");
1344
1345         snprintf(map_path, PATH_MAX, "/proc/%jd/gid_map",
1346                 (intmax_t) child_pid);
1347         if (map_zero) {
1348             snprintf(map_buf, MAP_BUF_SIZE, "0 %ld 1",
1349                     (intmax_t) getgid());
1350             gid_map = map_buf;
1351         }
1352         update_map(gid_map, map_path);
1353     }
1354
1355     /* Close the write end of the pipe, to signal to the child that we
1356        have updated the UID and GID maps. */
1357
1358     close(args.pipe_fd[1]);
1359
1360     if (waitpid(child_pid, NULL, 0) == \-1)      /* Wait for child */
1361         errExit("waitpid");
1362
1363     if (verbose)
1364         printf("%s: terminating\en", argv[0]);
1365
1366     exit(EXIT_SUCCESS);
1367 }
1368 .EE
1369 .SH SEE ALSO
1370 .BR newgidmap (1),      \" From the shadow package
1371 .BR newuidmap (1),      \" From the shadow package
1372 .BR clone (2),
1373 .BR ptrace (2),
1374 .BR setns (2),
1375 .BR unshare (2),
1376 .BR proc (5),
1377 .BR subgid (5),         \" From the shadow package
1378 .BR subuid (5),         \" From the shadow package
1379 .BR capabilities (7),
1380 .BR cgroup_namespaces (7),
1381 .BR credentials (7),
1382 .BR namespaces (7),
1383 .BR pid_namespaces (7)
1384 .PP
1385 The kernel source file
1386 .IR Documentation/admin\-guide/namespaces/resource\-control.rst .