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@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 > -- <http://www.alejandro-colomar.es/> GPG key fingerprint: A9348594CE31283A826FBDD8D57633D441E25BB5
Attachment:
OpenPGP_signature
Description: OpenPGP digital signature
