Re: For review: pid_namespaces(7) man page

[Eric W. Biederman]

"Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> writes:

> Eric et al,
>
> Eventually, there will be more namespace man pages, but let us start
> now with one for PID namespaces. The attached page aims to provide a
> fairly complete overview of PID namespaces.
>
> Eric, various pieces of the page are shifted out of other pages
> (clone(2), setns(2), etc.) and are derived from comments you've
> emailed me off list, so you are (jointly) in the copyright of the
> page. I've chosen the common license for man-pages; let me know if you
> have any objections to that license.

Interesting license.  It seems reasonable.

> I'm looking for review comments (corrections, improvements, additions,
> etc.) on this page. I've provided it in two forms inline below, and
> reviewers can comment comment on whichever form they are most
> comfortable with:
>
> 1) The rendered page as plain text
> 2) The *roff source (also attached); rendering that source will enable
> readers to see proper formatting for the page.
>
> Note that the namespaces(7) page referred to in this page is not yet
> finished; I'll send it out for review at a future time.
>
> Thanks,
>
> Michael
>
> ==========
> 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 migrate 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 standâ
>        alone system, and calls to fork(2), vfork(2), or clone(2)  will
>        produce  processes  with PIDs that are unique within the namesâ
>        pace.
>
>        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)).  Children that are orphaned within
>        the namespace will be reparented to this  process  rather  than
>        init(1).
>
>        If the "init" process of a PID namespace terminates, the kernel
>        terminates all of the processes 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  namesâ
>        pace.   In this case, a subsequent fork(2) into this PID namesâ
>        pace (e.g., from a process that has done a  setns(2)  into  the
>        namespace    using    an    open    file   descriptor   for   a
>        /proc/[pid]/ns/pid file corresponding to a process that was  in
>        the  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.

It may be useful to mention unshare in the case of fork(2) failing just
because that is such an easy mistake to make.

unshare(CLONE_NEWPID);
pid = fork();
waitpid(pid,...);
fork() -> ENOMEM 

>        Only  signals  for  which  the "init" process has established a
>        signal handler can be sent to the "init" process by other  memâ
>        bers  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 associâ
>        ated with those signals (respectively, terminating and stopping
>        the process).
>
>    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,  "visiâ
>        ble"  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 namespace can't see
>        processes in the parent and further removed ancestor namespace.
>        More  succinctly:  a  process  can see (e.g., send signals with
>        kill(2), set nice values with setpriority(2), etc.)  only  proâ
>        cesses 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  namesâ
>        pace 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 iniâ
>        tial 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 different PID namesâ
>        pace 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  chilâ
>        dren  subsequently created by the caller to be placed in a difâ
>        ferent PID namespace from the caller.  These calls do not, howâ
>        ever,  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 between PID
>        namespaces: the parent of a  process  is  either  in  the  same
>        namespace or resides in the immediate parent PID namespace.

This is mostly true.  With setns it is possible to have a parent
in a pid namespace several steps up the pid namespace hierarchy.

>        Every  thread  in  a process must be in the same PID namespace.
>        For this reason, the two following call sequences will fail:
>
>            unshare(CLONE_NEWPID);
>            clone(..., CLONE_VM, ...);    /* Fails */
>
>            setns(fd, CLONE_NEWPID);
>            clone(..., CLONE_VM, ...);    /* Fails */
>
>        Because the above unshare(2) and setns(2) calls only change the
>        PID  namespace  for created children, the clone(2) calls necesâ
>        sarily put the new thread in a different PID namespace from the
>        calling thread.

I don't know if it is interesting but these sequences also fail.  But I
suppose that is obvious?  Or documented at least Documented in the clone
manpage and unshare manpages.

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

            clone(..., CLONE_VM, ...);
            setns(fd, CLONE_NEWPID);     /* Fails */
              
>    Miscellaneous
>        After  creating a new PID namespace, it is useful for the child
>        to change its root directory 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.)

Should it be documented somewhere that /proc when mounted from a pid
namespace will use the pids of that pid namespace and /proc will only
show process for visible in the mounting pid namespace, even if that
mount of proc is accessed by processes in other pid namespaces?

You sort of say it here by saying it is useful to mount a new copy of
/proc, which it is.  I just don't see you coming out straight and saying
why it is.  It just seems to be implied.

>        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).
>
>        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  correâ
>        sponding PID value in the receiving process's PID namespace.
>
> CONFORMING TO
>        Namespaces are a Linux-specific feature.
>
> SEE ALSO
>        unshare(1),  clone(2),  setns(2),  unshare(2), proc(5), credenâ
>        tials(7), capabilities(7), user_namespaces(7), switch_root(8)
>
>
>
> Linux                         2013-01-14             PID_NAMESPACES(7)
>
>
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/