PID_NAMESPACES(7)                   Linux Programmer's Manual                   PID_NAMESPACES(7)



NAME
       pid_namespaces - overview of Linux PID namespaces

DESCRIPTION
       For an overview of namespaces, see namespaces(7).

       PID  namespaces  isolate  the process ID number space, meaning that processes in different
       PID namespaces can have the same PID.  PID namespaces allow containers  to  provide  func‐
       tionality  such as suspending/resuming the set of processes in the container and migrating
       the container to a new host while the processes inside the  container  maintain  the  same
       PIDs.

       PIDs  in  a  new PID namespace start at 1, somewhat like a standalone system, and calls to
       fork(2), vfork(2), or clone(2) will produce processes with PIDs that are unique within the
       namespace.

       Use of PID namespaces requires a kernel that is configured with the CONFIG_PID_NS option.

   The namespace init process
       The  first  process  created  in a new namespace (i.e., the process created using clone(2)
       with the CLONE_NEWPID flag, or the first child created  by  a  process  after  a  call  to
       unshare(2)  using  the CLONE_NEWPID flag) has the PID 1, and is the "init" process for the
       namespace (see init(1)).  A child process that is orphaned within the  namespace  will  be
       reparented  to  this process rather than init(1) (unless one of the ancestors of the child
       in the same PID namespace employed the prctl(2)  PR_GET_CHILD_SUBREAPER  command  to  mark
       itself as the reaper of orphaned descendant processes).

       If the "init" process of a PID namespace terminates, the kernel terminates all of the pro‐
       cesses in the namespace via a SIGKILL signal.  This behavior reflects the  fact  that  the
       "init" process is essential for the correct operation of a PID namespace.  In this case, a
       subsequent fork(2) into this PID namespace will fail with the error ENOMEM; it is not pos‐
       sible  to  create  a new processes in a PID namespace whose "init" process has terminated.
       Such scenarios can occur when, for example, a process uses an open file descriptor  for  a
       /proc/[pid]/ns/pid  file  corresponding  to  a process that was in a namespace to setns(2)
       into that namespace after the "init" process has terminated.   Another  possible  scenario
       can occur after a call to unshare(2): if the first child subsequently created by a fork(2)
       terminates, then subsequent calls to fork(2) will fail with ENOMEM.

       Only signals for which the "init" process has established a signal handler can be sent  to
       the  "init"  process by other members of the PID namespace.  This restriction applies even
       to privileged processes, and prevents other members of the PID namespace from accidentally
       killing the "init" process.

       Likewise,  a  process  in an ancestor namespace can—subject to the usual permission checks
       described in kill(2)—send signals to the "init" process of a child PID namespace  only  if
       the  "init"  process  has established a handler for that signal.  (Within the handler, the
       siginfo_t si_pid field described in sigaction(2) will be zero.)  SIGKILL  or  SIGSTOP  are
       treated exceptionally: these signals are forcibly delivered when sent from an ancestor PID
       namespace.  Neither of these signals can be caught by the  "init"  process,  and  so  will
       result  in  the usual actions associated with those signals (respectively, terminating and
       stopping the process).

       Starting with Linux 3.4, the reboot(2) system causes a signal to be sent to the  namespace
       "init" process.  See reboot(2) for more details.

   Nesting PID namespaces
       PID  namespaces  can  be  nested:  each PID namespace has a parent, except for the initial
       ("root") PID namespace.  The parent of a PID namespace is the PID namespace of the process
       that created the namespace using clone(2) or unshare(2).  PID namespaces thus form a tree,
       with all namespaces ultimately tracing their ancestry to the root namespace.

       A process is visible to other processes in its PID namespace, and to the processes in each
       direct  ancestor  PID  namespace  going  back to the root PID namespace.  In this context,
       "visible" means that one process can be the target of operations by another process  using
       system  calls  that specify a process ID.  Conversely, the processes in a child PID names‐
       pace can't see processes in the parent and further removed ancestor namespace.  More  suc‐
       cinctly:  a process can see (e.g., send signals with kill(2), set nice values with setpri‐
       ority(2), etc.) only processes contained in its own PID namespace and  in  descendants  of
       that namespace.

       A process has one process ID in each of the layers of the PID namespace hierarchy in which
       is visible, and walking back though each direct ancestor namespace through to the root PID
       namespace.   System  calls that operate on process IDs always operate using the process ID
       that is visible in the PID namespace of the caller.  A call to  getpid(2)  always  returns
       the PID associated with the namespace in which the process was created.

       Some processes in a PID namespace may have parents that are outside of the namespace.  For
       example, the parent of the initial process in the namespace  (i.e.,  the  init(1)  process
       with  PID  1)  is  necessarily  in  another namespace.  Likewise, the direct children of a
       process that uses setns(2) to cause its children to join a PID namespace are in a  differ‐
       ent  PID  namespace  from  the caller of setns(2).  Calls to getppid(2) for such processes
       return 0.

   setns(2) and unshare(2) semantics
       Calls to setns(2) that specify a PID namespace file descriptor  and  calls  to  unshare(2)
       with  the CLONE_NEWPID flag cause children subsequently created by the caller to be placed
       in a different PID namespace from the caller.  These calls do not, however, change the PID
       namespace  of  the calling process, because doing so would change the caller's idea of its
       own PID (as reported by getpid()), which would break many applications and libraries.

       To put things another way: a process's PID namespace membership  is  determined  when  the
       process  is created and cannot be changed thereafter.  Among other things, this means that
       the parental relationship between processes mirrors the parental relationship between  PID
       namespaces:  the  parent  of  a  process is either in the same namespace or resides in the
       immediate parent PID namespace.

   Compatibility of CLONE_NEWPID with other CLONE_* flags
       CLONE_NEWPID can't be combined with some other CLONE_* flags:

       *  CLONE_THREAD requires being in the same PID namespace in order that that the threads in
          a process can send signals to each other.  Similarly, it must be possible to see all of
          the threads of a processes in the proc(5) filesystem.

       *  CLONE_SIGHAND requires being in the same PID namespace; otherwise the process ID of the
          process  sending  a signal could not be meaningfully encoded when a signal is sent (see
          the description of the siginfo_t type in sigaction(2)).  A signal queue shared by  pro‐
          cesses in multiple PID namespaces will defeat that.

       *  CLONE_VM requires all of the threads to be in the same PID namespace, because, from the
          point of view of a core dump, if two processes share the same address  space  they  are
          threads and will be core dumped together.  When a core dump is written, the PID of each
          thread is written into the core dump.  Writing the process IDs could  not  meaningfully
          succeed if some of the process IDs were in a parent PID namespace.

       To  summarize:  there  is a technical requirement for each of CLONE_THREAD, CLONE_SIGHAND,
       and CLONE_VM to share a PID  namespace.   (Note  furthermore  that  in  clone(2)  requires
       CLONE_VM  to  be  specified  if  CLONE_THREAD  or CLONE_SIGHAND is specified.)  Thus, call
       sequences such as the following will fail (with the error EINVAL):

           unshare(CLONE_NEWPID);
           clone(..., CLONE_VM, ...);    /* Fails */

           setns(fd, CLONE_NEWPID);
           clone(..., CLONE_VM, ...);    /* Fails */

           clone(..., CLONE_VM, ...);
           setns(fd, CLONE_NEWPID);      /* Fails */

           clone(..., CLONE_VM, ...);
           unshare(CLONE_NEWPID);        /* Fails */

   /proc and PID namespaces
       A /proc filesystem shows (in the /proc/PID directories) only processes visible in the  PID
       namespace  of the process that performed the mount, even if the /proc filesystem is viewed
       from processes in other namespaces.

       After creating a new PID namespace, it is useful for the child to change its  root  direc‐
       tory  and mount a new procfs instance at /proc so that tools such as ps(1) work correctly.
       If a new mount namespace is simultaneously created by including CLONE_NEWNS in  the  flags
       argument  of clone(2) or unshare(2), then it isn't necessary to change the root directory:
       a new procfs instance can be mounted directly over /proc.

       From a shell, the command to mount /proc is:

           $ mount -t proc proc /proc

       Calling readlink(2) on the path /proc/self yields the process ID of the caller in the  PID
       namespace  of  the  procfs  mount (i.e., the PID namespace of the process that mounted the
       procfs).  This can be useful for introspection purposes, when a process wants to  discover
       its PID in other namespaces.

   Miscellaneous
       When  a  process  ID  is  passed over a UNIX domain socket to a process in a different PID
       namespace (see the description of SCM_CREDENTIALS in unix(7)), it is translated  into  the
       corresponding PID value in the receiving process's PID namespace.

CONFORMING TO
       Namespaces are a Linux-specific feature.

EXAMPLE
       See user_namespaces(7).

SEE ALSO
       clone(2),  setns(2),  unshare(2),  proc(5),  credentials(7),  capabilities(7), user_names‐
       paces(7), switch_root(8)

COLOPHON
       This page is part of release 3.74 of the Linux man-pages project.  A  description  of  the
       project,  information  about  reporting  bugs, and the latest version of this page, can be
       found at http://www.kernel.org/doc/man-pages/.



Linux                                       2014-09-21                          PID_NAMESPACES(7)