1 files changed, 384 insertions, 0 deletions
diff --git a/man/man7/credentials.7 b/man/man7/credentials.7
new file mode 100644
index 000000000..02427a9e5
--- /dev/null
+++ b/man/man7/credentials.7
@@ -0,0 +1,384 @@
+.\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" 2007-06-13 Creation
+.\"
+.TH credentials 7 (date) "Linux man-pages (unreleased)"
+.SH NAME
+credentials \- process identifiers
+.SH DESCRIPTION
+.SS Process ID (PID)
+Each process has a unique nonnegative integer identifier
+that is assigned when the process is created using
+.BR fork (2).
+A process can obtain its PID using
+.BR getpid (2).
+A PID is represented using the type
+.I pid_t
+(defined in
+.IR <sys/types.h> ).
+.P
+PIDs are used in a range of system calls to identify the process
+affected by the call, for example:
+.BR kill (2),
+.BR ptrace (2),
+.BR setpriority (2),
+.\" .BR sched_rr_get_interval (2),
+.\" .BR sched_getaffinity (2),
+.\" .BR sched_setaffinity (2),
+.\" .BR sched_getparam (2),
+.\" .BR sched_setparam (2),
+.\" .BR sched_setscheduler (2),
+.\" .BR sched_getscheduler (2),
+.BR setpgid (2),
+.\" .BR getsid (2),
+.BR setsid (2),
+.BR sigqueue (3),
+and
+.BR waitpid (2).
+.\" .BR waitid (2),
+.\" .BR wait4 (2),
+.P
+A process's PID is preserved across an
+.BR execve (2).
+.SS Parent process ID (PPID)
+A process's parent process ID identifies the process that created
+this process using
+.BR fork (2).
+A process can obtain its PPID using
+.BR getppid (2).
+A PPID is represented using the type
+.IR pid_t .
+.P
+A process's PPID is preserved across an
+.BR execve (2).
+.SS Process group ID and session ID
+Each process has a session ID and a process group ID,
+both represented using the type
+.IR pid_t .
+A process can obtain its session ID using
+.BR getsid (2),
+and its process group ID using
+.BR getpgrp (2).
+.P
+A child created by
+.BR fork (2)
+inherits its parent's session ID and process group ID.
+A process's session ID and process group ID are preserved across an
+.BR execve (2).
+.P
+Sessions and process groups are abstractions devised to support shell
+job control.
+A process group (sometimes called a "job") is a collection of
+processes that share the same process group ID;
+the shell creates a new process group for the process(es) used
+to execute single command or pipeline (e.g., the two processes
+created to execute the command "ls\ |\ wc" are placed in the
+same process group).
+A process's group membership can be set using
+.BR setpgid (2).
+The process whose process ID is the same as its process group ID is the
+\fIprocess group leader\fP for that group.
+.P
+A session is a collection of processes that share the same session ID.
+All of the members of a process group also have the same session ID
+(i.e., all of the members of a process group always belong to the
+same session, so that sessions and process groups form a strict
+two-level hierarchy of processes.)
+A new session is created when a process calls
+.BR setsid (2),
+which creates a new session whose session ID is the same
+as the PID of the process that called
+.BR setsid (2).
+The creator of the session is called the \fIsession leader\fP.
+.P
+All of the processes in a session share a
+.IR "controlling terminal" .
+The controlling terminal is established when the session leader
+first opens a terminal (unless the
+.B O_NOCTTY
+flag is specified when calling
+.BR open (2)).
+A terminal may be the controlling terminal of at most one session.
+.P
+At most one of the jobs in a session may be the
+.IR "foreground job" ;
+other jobs in the session are
+.IR "background jobs" .
+Only the foreground job may read from the terminal;
+when a process in the background attempts to read from the terminal,
+its process group is sent a
+.B SIGTTIN
+signal, which suspends the job.
+If the
+.B TOSTOP
+flag has been set for the terminal (see
+.BR termios (3)),
+then only the foreground job may write to the terminal;
+writes from background jobs cause a
+.B SIGTTOU
+signal to be generated, which suspends the job.
+When terminal keys that generate a signal (such as the
+.I interrupt
+key, normally control-C)
+are pressed, the signal is sent to the processes in the foreground job.
+.P
+Various system calls and library functions
+may operate on all members of a process group,
+including
+.BR kill (2),
+.BR killpg (3),
+.BR getpriority (2),
+.BR setpriority (2),
+.BR ioprio_get (2),
+.BR ioprio_set (2),
+.BR waitid (2),
+and
+.BR waitpid (2).
+See also the discussion of the
+.BR F_GETOWN ,
+.BR F_GETOWN_EX ,
+.BR F_SETOWN ,
+and
+.B F_SETOWN_EX
+operations in
+.BR fcntl (2).
+.SS User and group identifiers
+Each process has various associated user and group IDs.
+These IDs are integers, respectively represented using the types
+.I uid_t
+and
+.I gid_t
+(defined in
+.IR <sys/types.h> ).
+.P
+On Linux, each process has the following user and group identifiers:
+.IP \[bu] 3
+Real user ID and real group ID.
+These IDs determine who owns the process.
+A process can obtain its real user (group) ID using
+.BR getuid (2)
+.RB ( getgid (2)).
+.IP \[bu]
+Effective user ID and effective group ID.
+These IDs are used by the kernel to determine the permissions
+that the process will have when accessing shared resources such
+as message queues, shared memory, and semaphores.
+On most UNIX systems, these IDs also determine the
+permissions when accessing files.
+However, Linux uses the filesystem IDs described below
+for this task.
+A process can obtain its effective user (group) ID using
+.BR geteuid (2)
+.RB ( getegid (2)).
+.IP \[bu]
+Saved set-user-ID and saved set-group-ID.
+These IDs are used in set-user-ID and set-group-ID programs to save
+a copy of the corresponding effective IDs that were set when
+the program was executed (see
+.BR execve (2)).
+A set-user-ID program can assume and drop privileges by
+switching its effective user ID back and forth between the values
+in its real user ID and saved set-user-ID.
+This switching is done via calls to
+.BR seteuid (2),
+.BR setreuid (2),
+or
+.BR setresuid (2).
+A set-group-ID program performs the analogous tasks using
+.BR setegid (2),
+.BR setregid (2),
+or
+.BR setresgid (2).
+A process can obtain its saved set-user-ID (set-group-ID) using
+.BR getresuid (2)
+.RB ( getresgid (2)).
+.IP \[bu]
+Filesystem user ID and filesystem group ID (Linux-specific).
+These IDs, in conjunction with the supplementary group IDs described
+below, are used to determine permissions for accessing files; see
+.BR path_resolution (7)
+for details.
+Whenever a process's effective user (group) ID is changed,
+the kernel also automatically changes the filesystem user (group) ID
+to the same value.
+Consequently, the filesystem IDs normally have the same values
+as the corresponding effective ID, and the semantics for file-permission
+checks are thus the same on Linux as on other UNIX systems.
+The filesystem IDs can be made to differ from the effective IDs
+by calling
+.BR setfsuid (2)
+and
+.BR setfsgid (2).
+.IP \[bu]
+Supplementary group IDs.
+This is a set of additional group IDs that are used for permission
+checks when accessing files and other shared resources.
+Before Linux 2.6.4,
+a process can be a member of up to 32 supplementary groups;
+since Linux 2.6.4,
+a process can be a member of up to 65536 supplementary groups.
+The call
+.I sysconf(_SC_NGROUPS_MAX)
+can be used to determine the number of supplementary groups
+of which a process may be a member.
+.\" Since Linux 2.6.4, the limit is visible via the read-only file
+.\" /proc/sys/kernel/ngroups_max.
+.\" As at 2.6.22-rc2, this file is still read-only.
+A process can obtain its set of supplementary group IDs using
+.BR getgroups (2).
+.P
+A child process created by
+.BR fork (2)
+inherits copies of its parent's user and groups IDs.
+During an
+.BR execve (2),
+a process's real user and group ID and supplementary
+group IDs are preserved;
+the effective and saved set IDs may be changed, as described in
+.BR execve (2).
+.P
+Aside from the purposes noted above,
+a process's user IDs are also employed in a number of other contexts:
+.IP \[bu] 3
+when determining the permissions for sending signals (see
+.BR kill (2));
+.IP \[bu]
+when determining the permissions for setting
+process-scheduling parameters (nice value, real time
+scheduling policy and priority, CPU affinity, I/O priority) using
+.BR setpriority (2),
+.BR sched_setaffinity (2),
+.BR sched_setscheduler (2),
+.BR sched_setparam (2),
+.BR sched_setattr (2),
+and
+.BR ioprio_set (2);
+.IP \[bu]
+when checking resource limits (see
+.BR getrlimit (2));
+.IP \[bu]
+when checking the limit on the number of inotify instances
+that the process may create (see
+.BR inotify (7)).
+.\"
+.SS Modifying process user and group IDs
+Subject to rules described in the relevant manual pages,
+a process can use the following APIs to modify its user and group IDs:
+.TP
+.BR setuid (2)\~(\c
+.BR setgid (2))
+Modify the process's real (and possibly effective and saved-set)
+user (group) IDs.
+.TP
+.BR seteuid (2)\~(\c
+.BR setegid (2))
+Modify the process's effective user (group) ID.
+.TP
+.BR setfsuid (2)\~(\c
+.BR setfsgid (2))
+Modify the process's filesystem user (group) ID.
+.TP
+.BR setreuid (2)\~(\c
+.BR setregid (2))
+Modify the process's real and effective (and possibly saved-set)
+user (group) IDs.
+.TP
+.BR setresuid (2)\~(\c
+.BR setresgid (2))
+Modify the process's real, effective, and saved-set user (group) IDs.
+.TP
+.BR setgroups (2)
+Modify the process's supplementary group list.
+.P
+Any changes to a process's effective user (group) ID
+are automatically carried over to the process's
+filesystem user (group) ID.
+Changes to a process's effective user or group ID can also affect the
+process "dumpable" attribute, as described in
+.BR prctl (2).
+.P
+Changes to process user and group IDs can affect the capabilities
+of the process, as described in
+.BR capabilities (7).
+.SH STANDARDS
+Process IDs, parent process IDs, process group IDs, and session IDs
+are specified in POSIX.1.
+The real, effective, and saved set user and groups IDs,
+and the supplementary group IDs, are specified in POSIX.1.
+.P
+The filesystem user and group IDs are a Linux extension.
+.SH NOTES
+Various fields in the
+.IR /proc/ pid /status
+file show the process credentials described above.
+See
+.BR proc (5)
+for further information.
+.P
+The POSIX threads specification requires that
+credentials are shared by all of the threads in a process.
+However, at the kernel level, Linux maintains separate user and group
+credentials for each thread.
+The NPTL threading implementation does some work to ensure
+that any change to user or group credentials
+(e.g., calls to
+.BR setuid (2),
+.BR setresuid (2))
+is carried through to all of the POSIX threads in a process.
+See
+.BR nptl (7)
+for further details.
+.SH SEE ALSO
+.BR bash (1),
+.BR csh (1),
+.BR groups (1),
+.BR id (1),
+.BR newgrp (1),
+.BR ps (1),
+.BR runuser (1),
+.BR setpriv (1),
+.BR sg (1),
+.BR su (1),
+.BR access (2),
+.BR execve (2),
+.BR faccessat (2),
+.BR fork (2),
+.BR getgroups (2),
+.BR getpgrp (2),
+.BR getpid (2),
+.BR getppid (2),
+.BR getsid (2),
+.BR kill (2),
+.BR setegid (2),
+.BR seteuid (2),
+.BR setfsgid (2),
+.BR setfsuid (2),
+.BR setgid (2),
+.BR setgroups (2),
+.BR setpgid (2),
+.BR setresgid (2),
+.BR setresuid (2),
+.BR setsid (2),
+.BR setuid (2),
+.BR waitpid (2),
+.BR euidaccess (3),
+.BR initgroups (3),
+.BR killpg (3),
+.BR tcgetpgrp (3),
+.BR tcgetsid (3),
+.BR tcsetpgrp (3),
+.BR group (5),
+.BR passwd (5),
+.BR shadow (5),
+.BR capabilities (7),
+.BR namespaces (7),
+.BR path_resolution (7),
+.BR pid_namespaces (7),
+.BR pthreads (7),
+.BR signal (7),
+.BR system_data_types (7),
+.BR unix (7),
+.BR user_namespaces (7),
+.BR sudo (8)