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@xxxxxxxxxxxxxxx> > --- > 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 -- Alejandro Colomar Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/ http://www.alejandro-colomar.es/
