original/man7/credentials.7

   1 .\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" 2007-06-13 Creation
  24 .\"
  25 .TH CREDENTIALS 7 2008-06-03 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 credentials \- process identifiers
  28 .SH DESCRIPTION
  29 .SS Process ID (PID)
  30 Each process has a unique nonnegative integer identifier
  31 that is assigned when the process is created using
  32 .BR fork (2).
  33 A process can obtain its PID using
  34 .BR getpid (2).
  35 A PID is represented using the type
  36 .I pid_t
  37 (defined in
  38 .IR <sys/types.h> ).
  39
  40 PIDs are used in a range of system calls to identify the process
  41 affected by the call, for example:
  42 .BR kill (2),
  43 .BR ptrace (2),
  44 .BR setpriority (2)
  45 .\" .BR sched_rr_get_interval (2),
  46 .\" .BR sched_getaffinity (2),
  47 .\" .BR sched_setaffinity (2),
  48 .\" .BR sched_getparam (2),
  49 .\" .BR sched_setparam (2),
  50 .\" .BR sched_setscheduler (2),
  51 .\" .BR sched_getscheduler (2),
  52 .BR setpgid (2),
  53 .\" .BR getsid (2),
  54 .BR setsid (2),
  55 .BR sigqueue (2),
  56 and
  57 .BR waitpid (2).
  58 .\" .BR waitid (2),
  59 .\" .BR wait4 (2),
  60
  61 A process's PID is preserved across an
  62 .BR execve (2).
  63 .SS Parent Process ID (PPID)
  64 A process's parent process ID identifies the process that created
  65 this process using
  66 .BR fork (2).
  67 A process can obtain its PPID using
  68 .BR getppid (2).
  69 A PPID is represented using the type
  70 .IR pid_t .
  71
  72 A process's PPID is preserved across an
  73 .BR execve (2).
  74 .SS Process Group ID and Session ID
  75 Each process has a session ID and a process group ID,
  76 both represented using the type
  77 .IR pid_t .
  78 A process can obtain its session ID using
  79 .BR getsid (2),
  80 and its process group ID using
  81 .BR getpgrp (2).
  82
  83 A child created by
  84 .BR fork (2)
  85 inherits its parent's session ID and process group ID.
  86 A process's session ID and process group ID are preserved across an
  87 .BR execve (2).
  88
  89 Sessions and process groups are abstractions devised to support shell
  90 job control.
  91 A process group (sometimes called a "job") is a collection of
  92 processes that share the same process group ID;
  93 the shell creates a new process group for the process(es) used
  94 to execute single command or pipeline (e.g., the two processes
  95 created to execute the command "ls\ |\ wc" are placed in the
  96 same process group).
  97 A process's group membership can be set using
  98 .BR setpgid (2).
  99 The process whose process ID is the same as its process group ID is the
 100 \fIprocess group leader\fP for that group.
 101
 102 A session is a collection of processes that share the same session ID.
 103 All of the members of a process group also have the same session ID
 104 (i.e., all of the members of a process group always belong to the
 105 same session, so that sessions and process groups form a strict
 106 two-level hierarchy of processes.)
 107 A new session is created when a process calls
 108 .BR setsid (2),
 109 which creates a new session whose session ID is the same
 110 as the PID of the process that called
 111 .BR setsid (2).
 112 The creator of the session is called the \fIsession leader\fP.
 113 .SS User and Group Identifiers
 114 Each process has various associated user and groups IDs.
 115 These IDs are integers, respectively represented using the types
 116 .I uid_t
 117 and
 118 .I gid_t
 119 (defined in
 120 .IR <sys/types.h> ).
 121
 122 On Linux, each process has the following user and group identifiers:
 123 .IP * 3
 124 Real user ID and real group ID.
 125 These IDs determine who owns the process.
 126 A process can obtain its real user (group) ID using
 127 .BR getuid (2)
 128 .RB ( getgid (2)).
 129 .IP *
 130 Effective user ID and effective group ID.
 131 These IDs are used by the kernel to determine the permissions
 132 that the process will have when accessing shared resources such
 133 as message queues, shared memory, and semaphores.
 134 On most UNIX systems, these IDs also determine the
 135 permissions when accessing files.
 136 However, Linux uses the file system IDs described below
 137 for this task.
 138 A process can obtain its effective user (group) ID using
 139 .BR geteuid (2)
 140 .RB ( getegid (2)).
 141 .IP *
 142 Saved set-user-ID and saved set-group-ID.
 143 These IDs are used in set-user-ID and set-group-ID programs to save
 144 a copy of the corresponding effective IDs that were set when
 145 the program was executed (see
 146 .BR execve (2)).
 147 A set-user-ID program can assume and drop privileges by
 148 switching its effective user ID back and forth between the values
 149 in its real user ID and saved set-user-ID.
 150 This switching is done via calls to
 151 .BR seteuid (2),
 152 .BR setreuid (2),
 153 or
 154 .BR setresuid (2).
 155 A set-group-ID program performs the analogous tasks using
 156 .BR setegid (2),
 157 .BR setregid (2),
 158 or
 159 .BR setresgid (2).
 160 A process can obtain its saved set-user-ID (set-group-ID) using
 161 .BR getresuid (2)
 162 .RB ( getresgid (2)).
 163 .IP *
 164 File system user ID and file system group ID (Linux-specific).
 165 These IDs, in conjunction with the supplementary group IDs described
 166 below, are used to determine permissions for accessing files; see
 167 .BR path_resolution (7)
 168 for details.
 169 Whenever a process's effective user (group) ID is changed,
 170 the kernel also automatically changes the file system user (group) ID
 171 to the same value.
 172 Consequently, the file system IDs normally have the same values
 173 as the corresponding effective ID, and the semantics for file-permission
 174 checks are thus the same on Linux as on other UNIX systems.
 175 The file system IDs can be made to differ from the effective IDs
 176 by calling
 177 .BR setfsuid (2)
 178 and
 179 .BR setfsgid (2).
 180 .IP *
 181 Supplementary group IDs.
 182 This is a set of additional group IDs that are used for permission
 183 checks when accessing files and other shared resources.
 184 On Linux kernels before 2.6.4,
 185 a process can be a member of up to 32 supplementary groups;
 186 since kernel 2.6.4,
 187 a process can be a member of up to 65536 supplementary groups.
 188 The call
 189 .I sysconf(_SC_NGROUPS_MAX)
 190 can be used to determine the number of supplementary groups
 191 of which a process may be a member.
 192 .\" Since kernel 2.6.4, the limit is visible via the read-only file
 193 .\" /proc/sys/kernel/ngroups_max.
 194 .\" As at 2.6.22-rc2, this file is still read-only.
 195 A process can obtain its set of supplementary group IDs using
 196 .BR getgroups (2),
 197 and can modify the set using
 198 .BR setgroups (2).
 199 .PP
 200 A child process created by
 201 .BR fork (2)
 202 inherits copies of its parent's user and groups IDs.
 203 During an
 204 .BR execve (2),
 205 a process's real user and group ID and supplementary
 206 group IDs are preserved;
 207 the effective and saved set IDs may be changed, as described in
 208 .BR execve (2).
 209
 210 Aside from the purposes noted above,
 211 a process's user IDs are also employed in a number of other contexts:
 212 .IP * 3
 213 when determining the permissions for sending signals \(em see
 214 .BR kill (2);
 215 .IP *
 216 when determining the permissions for setting
 217 process-scheduling parameters (nice value, real time
 218 scheduling policy and priority, CPU affinity, I/O priority) using
 219 .BR setpriority (2),
 220 .BR sched_setaffinity (2),
 221 .BR sched_setscheduler (2),
 222 .BR sched_setparam (2),
 223 and
 224 .BR ioprio_set (2);
 225 .IP *
 226 when checking resource limits; see
 227 .BR getrlimit (2);
 228 .IP *
 229 when checking the limit on the number of inotify instances
 230 that the process may create; see
 231 .BR inotify (7).
 232 .SH "CONFORMING TO"
 233 Process IDs, parent process IDs, process group IDs, and session IDs
 234 are specified in POSIX.1-2001.
 235 The real, effective, and saved set user and groups IDs,
 236 and the supplementary group IDs, are specified in POSIX.1-2001.
 237 The file system user and group IDs are a Linux extension.
 238 .SH NOTES
 239 The POSIX threads specification requires that
 240 credentials are shared by all of the threads in a process.
 241 However, at the kernel level, Linux maintains separate user and group
 242 credentials for each thread.
 243 The NPTL threading implementation does some work to ensure
 244 that any change to user or group credentials
 245 (e.g., calls to
 246 .BR setuid (2),
 247 .BR setresuid (2),
 248 etc.)
 249 is carried through to all of the POSIX threads in a process.
 250 .SH "SEE ALSO"
 251 .BR bash (1),
 252 .BR csh (1),
 253 .BR ps (1),
 254 .BR access (2),
 255 .BR execve (2),
 256 .BR faccessat (2),
 257 .BR fork (2),
 258 .BR getpgrp (2),
 259 .BR getpid (2),
 260 .BR getppid (2),
 261 .BR getsid (2),
 262 .BR kill (2),
 263 .BR killpg (2),
 264 .BR setegid (2),
 265 .BR seteuid (2),
 266 .BR setfsgid (2),
 267 .BR setfsuid (2),
 268 .BR setgid (2),
 269 .BR setgroups (2),
 270 .BR setresgid (2),
 271 .BR setresuid (2),
 272 .BR setuid (2),
 273 .BR waitpid (2),
 274 .BR euidaccess (3),
 275 .BR initgroups (3),
 276 .BR tcgetpgrp (3),
 277 .BR tcsetpgrp (3),
 278 .BR capabilities (7),
 279 .BR path_resolution (7),
 280 .BR unix (7)