proc(5)'s sashimi

[Alejandro Colomar <alx@kernel.org>]

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

Hi!

The day has come to cut the proc(5) tuna fish in very little pieces.
As a first step, I'm pasting the contents of proc(5) into little
files, without changing any contents (not even the formatting).  For
example see the two files at the bottom of this email.

I'd like to hear any comments before pushing such a change to the repo.
I'll soon post a branch called 'proc' to my repo (I'll ping when it's
done), so you can observe the changes).

One of the questions I have at the moment is how should we call the
pages, and what should we write in the TH and NAME.  Branden, do you
have any comments on that?  I used underscores for the page title and
file name, but for the NAME I used slashes (so the actual name of the
interface).  I didn't do any italics in the name, though, so /pid/ is
no special in the name.

Cheers,
Alex

---

$ MANWIDTH=72 man ./proc_pid_gid_map.5 | cat
proc_pid_gid_map(5)       File Formats Manual      proc_pid_gid_map(5)

NAME
     /proc/pid/gid_map - group ID mappings

DESCRIPTION
     /proc/pid/gid_map (since Linux 3.5)
            See user_namespaces(7).

SEE ALSO
     proc(5)

Linux man‐pages (unreleased)    (date)             proc_pid_gid_map(5)


$ MANWIDTH=72 man ./proc_pid_attr.5 | cat
proc_pid_attr(5)          File Formats Manual         proc_pid_attr(5)

NAME
     /proc/pid/attr/ - security‐related attributes

DESCRIPTION
     /proc/pid/attr/
            The  files  in  this directory provide an API for security
            modules.  The contents of this directory  are  files  that
            can  be  read and written in order to set security‐related
            attributes.  This directory was added to support  SELinux,
            but  the  intention  was that the API be general enough to
            support other security modules.  For the purpose of expla‐
            nation, examples of how SELinux uses these files are  pro‐
            vided below.

            This  directory  is present only if the kernel was config‐
            ured with CONFIG_SECURITY.

     /proc/pid/attr/current (since Linux 2.6.0)
            The contents of this file represent the  current  security
            attributes of the process.

            In  SELinux, this file is used to get the security context
            of a process.  Prior to Linux 2.6.11, this file could  not
            be  used  to  set the security context (a write was always
            denied), since SELinux limited  process  security  transi‐
            tions    to    execve(2)    (see    the   description   of
            /proc/pid/attr/exec, below).  Since Linux 2.6.11,  SELinux
            lifted  this restriction and began supporting "set" opera‐
            tions via writes to this node if authorized by policy, al‐
            though use of this operation is only suitable for applica‐
            tions that are trusted to maintain any desired  separation
            between the old and new security contexts.

            Prior  to  Linux  2.6.28,  SELinux  did  not allow threads
            within a multithreaded process to set their security  con‐
            text  via  this  node  as  it would yield an inconsistency
            among the security contexts of  the  threads  sharing  the
            same  memory  space.   Since  Linux 2.6.28, SELinux lifted
            this restriction and began supporting "set" operations for
            threads within a multithreaded process if the new security
            context is bounded by the old security context, where  the
            bounded  relation is defined in policy and guarantees that
            the new security context has a subset of  the  permissions
            of the old security context.

            Other  security modules may choose to support "set" opera‐
            tions via writes to this node.

     /proc/pid/attr/exec (since Linux 2.6.0)
            This file represents  the  attributes  to  assign  to  the
            process upon a subsequent execve(2).

            In  SELinux, this is needed to support role/domain transi‐
            tions, and execve(2) is the preferred point to  make  such
            transitions because it offers better control over the ini‐
            tialization  of  the process in the new security label and
            the inheritance of state.  In SELinux, this  attribute  is
            reset  on execve(2) so that the new program reverts to the
            default behavior for any execve(2) calls that it may make.
            In   SELinux,   a   process   can   set   only   its   own
            /proc/pid/attr/exec attribute.

     /proc/pid/attr/fscreate (since Linux 2.6.0)
            This  file  represents  the  attributes to assign to files
            created by subsequent calls  to  open(2),  mkdir(2),  sym‐
            link(2), and mknod(2)

            SELinux  employs  this  file to support creation of a file
            (using the aforementioned system calls) in a secure state,
            so that there is no risk of inappropriate access being ob‐
            tained between the time of creation and the time that  at‐
            tributes  are set.  In SELinux, this attribute is reset on
            execve(2), so that the new program reverts to the  default
            behavior  for any file creation calls it may make, but the
            attribute will persist across multiple file creation calls
            within a  program  unless  it  is  explicitly  reset.   In
            SELinux,    a    process    can    set    only   its   own
            /proc/pid/attr/fscreate attribute.

     /proc/pid/attr/keycreate (since Linux 2.6.18)
            If a process writes a security context into this file, all
            subsequently created keys  (add_key(2))  will  be  labeled
            with  this context.  For further information, see the ker‐
            nel source file  Documentation/security/keys/core.rst  (or
            file Documentation/security/keys.txt between Linux 3.0 and
            Linux 4.13, or Documentation/keys.txt before Linux 3.0).

     /proc/pid/attr/prev (since Linux 2.6.0)
            This file contains the security context of the process be‐
            fore  the  last  execve(2); that is, the previous value of
            /proc/pid/attr/current.

     /proc/pid/attr/socketcreate (since Linux 2.6.18)
            If a process writes a security context into this file, all
            subsequently created sockets will  be  labeled  with  this
            context.

SEE ALSO
     proc(5)

Linux man‐pages (unreleased)    (date)                proc_pid_attr(5)

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

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