Re: [patch] Add docs on mount namespace rootfs access and pid namespace pid mapping

[Alejandro Colomar <alx.manpages@gmail.com>]

[-- Attachment #1.1: Type: text/plain, Size: 10371 bytes --]

Hi Craig,

I'm checking old mail, and see that this thread was unresolved.  Do
you still have this patch around and are interested in sending it?\

Thanks,

Alex

On 3/14/22 15:05, Alejandro Colomar (man-pages) wrote:
> Hi Craig,
> 
> On 3/14/22 07:10, Craig Ringer wrote:
>> The attached 4-patch series adds information to the mount namespaces
>> and pid namespaces documentation to help users discover how to access
>> important related information.
>>
>> 1. Elaborate on /proc/[pid]/root and x-ref it
>> 2. Mention /proc/$pid/status NSpid in pid_namespaces
>> 3. Mention pid namespaces /proc/[pid]/root/proc
>> 4. Additional namespaces related x-refs
>>
>> 1): Mention /proc/[pid]/root in mount_namespaces(7) to help people
>> discover how to access the file system tree seen by a process in
>> another mount namespace. In the proc (5) entry for it, warn about the
>> possibly-confusing semantics of readlink() vs following the path in
>> the vfs layer.
>>
>>   Adding because I found it difficult to figure out how to access the
>> file system seen by another process in a disjoint chroot in a
>> non-ancestor mount namespace.
>>
>> 2): Mention the /proc/[pid]/status NSpid field and related fields in
>> pid_namespaces (7) to help people discover how to map process IDs
>> between a parent namespace and any child namespace(s) the process is
>> in.
>>
>>   Adding because I found it difficult to discover how to map pids
>> between namespaces.
>>
>> 3): Mention how /proc/[pid]/root/proc behaves when [pid] is in a
>> different pid namespace. It's useful to know that you can see another
>> process's view of procfs via its /proc/[pid]/root link.
>>
>> 4): Some minor cross-references and see-alsos that would've helped me
>> during unrelated past efforts.
> 
> PATCH 1/4:
> 
>> Subject: [PATCH v1 1/4] Elaborate on /proc/[pid]/root and x-ref it
> 
> Please mention the modified page(s) in the Subject line.
> See <https://www.kernel.org/doc/man-pages/patches.html>.
> 
> Also, per the same documentation, please send the patches inline (or
> inline + attached if your mailer is likely to break the patches) if you
> can, since it's easier for us to review and work with them.
> 
>>
>> Mention /proc/[pid]/{root,cwd,exe,fds} in mount_namespaces (7)
>> to help users understand how to access the file system tree of
>> a process in different mount namespace and possibly-disjoint
>> chroot.
>>
>> In proc (5) provide a little more detail on how links like
>> /proc/[pid]/root behave when read with readlink (2) vs when
>> resolved via kernel vfs layer path lookup. It can be quite confusing
>> that "readlink /proc/$pid/root" prints "/" so
>> "ls $(readlink /proc/$pid/root)" has the same result as "ls /" but
>> "ls /proc/$pid/root/" actually lists the target pid's root.
>>
>> Signed-off-by: Craig Ringer <craig.ringer@2ndquadrant.com>
>> ---
>>  man5/proc.5             | 29 ++++++++++++++++++++++++++++-
>>  man7/mount_namespaces.7 | 14 ++++++++++++++
>>  2 files changed, 42 insertions(+), 1 deletion(-)
>>
>> diff --git a/man5/proc.5 b/man5/proc.5
>> index c6684620e..2eed160e2 100644
>> --- a/man5/proc.5
>> +++ b/man5/proc.5
>> @@ -658,6 +658,12 @@ are not available if the main thread has already terminated
>>  (typically by calling
>>  .BR pthread_exit (3)).
>>  .IP
>> +If the process is in a chroot and/or a different mount namespace, reading the
> 
> Please use semantic newlines
> (i.e., break after that comma, instead of just before col 80).
> See man-pages(7):
> 
> STYLE GUIDE
>        [...]
>    Use semantic newlines
>        In the source of a manual page, new sentences  should  be
>        started on new lines, long sentences should be split into
>        lines  at  clause breaks (commas, semicolons, colons, and
>        so on), and long clauses should be split at phrase bound‐
>        aries.  This convention,  sometimes  known  as  "semantic
>        newlines",  makes it easier to see the effect of patches,
>        which often operate at the level of individual sentences,
>        clauses, or phrases.
> 
>> +symlink path will return the executable path relative to the process's root.
>> +Opening the path within the kernel vfs layer will yield the actual executable
>> +contents even if  the path does may not exist within the currently active mount
>> +namespace.
>> +.IP
>>  Permission to dereference or read
>>  .RB ( readlink (2))
>>  this symbolic link is governed by a ptrace access mode
>> @@ -1830,7 +1836,8 @@ and
>>  .IP
>>  Note however that this file is not merely a symbolic link.
>>  It provides the same view of the filesystem (including namespaces and the
>> -set of per-process mounts) as the process itself.
>> +set of per-process mounts) as the process itself
>> +if dereferenced via the kernel vfs layer.
>>  An example illustrates this point.
>>  In one terminal, we start a shell in new user and mount namespaces,
>>  and in that shell we create some new mounts:
>> @@ -1866,6 +1873,26 @@ sh2# \fBls /usr | wc \-l\fP                  # /usr in initial NS
>>  .EE
>>  .in
>>  .IP
>> +If the target process is in a different mount namespace
>> +and has a different root, following the
>> +.B /proc/[pid]/root
>> +link directly will resolve paths relative to the target
>> +process's root. But
>> +.BR readlink (2)
>> +will return the root path as seen from within the target process's mount
>> +namespace. Tools that canonicalize paths or resolve symbolic links in
> 
> Always start sentences after '.' in a new line.
> That's already covered by "semantic newlines" (see above),
> but it's especially important in this case because
> groff(1) prints (at least) 2 spaces after '.' normally,
> but if you write it this way it doesn't.
> 
> BTW, Branden,
> I CCd you because I didn't find this documented in groff(7),
> or at least I couldn't find it.
> I tried /\.[^ [a-z]] and also keywords like period, point or dot,
> but no luck.
> Is it documented anywhere?
> 
>> +user-space will not be able to see the target process's root. So
>> +.B ls $(realpath /proc/[pid]/root)
> 
> Commands should use italics (.I) instead of bold (.B).
> See man-pages(7):
> 
> [
> STYLE GUIDE
>        [...]
>    Formatting conventions (general)
>        [...]
>        Complete commands should, if long, be written as  an  in‐
>        dented  line  on  their own, with a blank line before and
>        after the command, for example
> 
>            man 7 man-pages
> 
>        If the command is short, then it can be  included  inline
>        in  the  text,  in italic format, for example, man 7 man-
>        pages.  In this case, it may be worth  using  nonbreaking
>        spaces  (\~)  at suitable places in the command.  Command
>        options should be written in italics (e.g., -l).
> ]
> 
> Variable text inside running italics should be in roman.
> So instead of writing [pid], you should use:
> .IR "ls $(realpath /proc/" pid /root)
> 
> See groff_man_style(7):
> 
> [
> Description
>        [...]
>    Font style macros
>        [...]
>        .I [text]
>               Set text in italics.  If the macro is given no ar‐
>               guments, the text of the next input line is set in
>               italics.
> 
>               Use italics for file and path names, for  environ‐
>               ment  variables, for C data types, for enumeration
>               or  preprocessor  constants  in  C,  for  variable
>               (user-determined) portions of syntax synopses, for
>               the first occurrence (only) of a technical concept
>               being  introduced,  for  names  of journals and of
>               literary works longer than an  article,  and  any‐
>               where  a  parameter  requiring  replacement by the
>               user is encountered.  An exception involves  vari‐
>               able  text  in a context that is already marked up
>               in italics, such as file or path names with  vari‐
>               able components; in such cases, follow the conven‐
>               tion  of  mathematical typography: set the file or
>               path name in italics as usual but  use  roman  for
>               the  variable  part  (see  .IR and .RI below), and
>               italics again in running roman text when referring
>               to the variable material.
> ]
> 
>> +will expand to
>> +.B ls /
>> +and print the root of the invoking shell, but
>> +.B ls /proc/[pid]/root/
>> +will list the contents of
>> +.B /
>> +as seen by [pid]. See
> 
> In this case, use:
> .IR pid .
> 
> Se rationale above.
> 
>> +.BR mount_namespaces (7)
>> +for details.
>> +.IP
>>  .\" The following was still true as at kernel 2.6.13
>>  In a multithreaded process, the contents of the
>>  .I /proc/[pid]/root
> 
> BTW, I now realize that the manual page is currently incorrectly
> formatted according to what I just said above.
> So, please don't fix that in your patch,
> so that the whole page is consistent with itself,
> and I'll fix the whole page after your patch
> (and some other pages that seem to the same problem). :)
> 
>> diff --git a/man7/mount_namespaces.7 b/man7/mount_namespaces.7
>> index 7725b341f..98bfd864c 100644
>> --- a/man7/mount_namespaces.7
>> +++ b/man7/mount_namespaces.7
>> @@ -75,6 +75,20 @@ and
>>  in either mount namespace will not (by default) affect the
>>  mount list seen in the other namespace
>>  (but see the following discussion of shared subtrees).
>> +.PP
>> +The pseudo-symlinks
>> +.IR /proc/[pid]/exe ,
>> +.IR /proc/[pid]/root ,
>> +.IR /proc/[pid]/fds ,
>> +and
>> +.IR /proc/[pid]/cwd
>> +provide views into the mount namespace of
>> +.IR [pid]
>> +from outside that namespace.
>> +These links provide a way to access the mount namespace seen by another process
>> +- even if its root is disjoint from the current process's root. See
>> +.BR proc (5)
>> +for details and caveats.
>>  .\"
>>  .SH SHARED SUBTREES
>>  After the implementation of mount namespaces was completed,
>> -- 
>> 2.34.1
>>
> 
> Thanks!
> 
> Alex
> 

-- 
<http://www.alejandro-colomar.es/>
GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]