man7/credentials.7

   1 .\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" 2007-06-13 Creation
   6 .\"
   7 .TH credentials 7 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 credentials \- process identifiers
  10 .SH DESCRIPTION
  11 .SS Process ID (PID)
  12 Each process has a unique nonnegative integer identifier
  13 that is assigned when the process is created using
  14 .BR fork (2).
  15 A process can obtain its PID using
  16 .BR getpid (2).
  17 A PID is represented using the type
  18 .I pid_t
  19 (defined in
  20 .IR <sys/types.h> ).
  21 .P
  22 PIDs are used in a range of system calls to identify the process
  23 affected by the call, for example:
  24 .BR kill (2),
  25 .BR ptrace (2),
  26 .BR setpriority (2),
  27 .\" .BR sched_rr_get_interval (2),
  28 .\" .BR sched_getaffinity (2),
  29 .\" .BR sched_setaffinity (2),
  30 .\" .BR sched_getparam (2),
  31 .\" .BR sched_setparam (2),
  32 .\" .BR sched_setscheduler (2),
  33 .\" .BR sched_getscheduler (2),
  34 .BR setpgid (2),
  35 .\" .BR getsid (2),
  36 .BR setsid (2),
  37 .BR sigqueue (3),
  38 and
  39 .BR waitpid (2).
  40 .\" .BR waitid (2),
  41 .\" .BR wait4 (2),
  42 .P
  43 A process's PID is preserved across an
  44 .BR execve (2).
  45 .SS Parent process ID (PPID)
  46 A process's parent process ID identifies the process that created
  47 this process using
  48 .BR fork (2).
  49 A process can obtain its PPID using
  50 .BR getppid (2).
  51 A PPID is represented using the type
  52 .IR pid_t .
  53 .P
  54 A process's PPID is preserved across an
  55 .BR execve (2).
  56 .SS Process group ID and session ID
  57 Each process has a session ID and a process group ID,
  58 both represented using the type
  59 .IR pid_t .
  60 A process can obtain its session ID using
  61 .BR getsid (2),
  62 and its process group ID using
  63 .BR getpgrp (2).
  64 .P
  65 A child created by
  66 .BR fork (2)
  67 inherits its parent's session ID and process group ID.
  68 A process's session ID and process group ID are preserved across an
  69 .BR execve (2).
  70 .P
  71 Sessions and process groups are abstractions devised to support shell
  72 job control.
  73 A process group (sometimes called a "job") is a collection of
  74 processes that share the same process group ID;
  75 the shell creates a new process group for the process(es) used
  76 to execute single command or pipeline (e.g., the two processes
  77 created to execute the command "ls\ |\ wc" are placed in the
  78 same process group).
  79 A process's group membership can be set using
  80 .BR setpgid (2).
  81 The process whose process ID is the same as its process group ID is the
  82 \fIprocess group leader\fP for that group.
  83 .P
  84 A session is a collection of processes that share the same session ID.
  85 All of the members of a process group also have the same session ID
  86 (i.e., all of the members of a process group always belong to the
  87 same session, so that sessions and process groups form a strict
  88 two-level hierarchy of processes.)
  89 A new session is created when a process calls
  90 .BR setsid (2),
  91 which creates a new session whose session ID is the same
  92 as the PID of the process that called
  93 .BR setsid (2).
  94 The creator of the session is called the \fIsession leader\fP.
  95 .P
  96 All of the processes in a session share a
  97 .IR "controlling terminal" .
  98 The controlling terminal is established when the session leader
  99 first opens a terminal (unless the
 100 .B O_NOCTTY
 101 flag is specified when calling
 102 .BR open (2)).
 103 A terminal may be the controlling terminal of at most one session.
 104 .P
 105 At most one of the jobs in a session may be the
 106 .IR "foreground job" ;
 107 other jobs in the session are
 108 .IR "background jobs" .
 109 Only the foreground job may read from the terminal;
 110 when a process in the background attempts to read from the terminal,
 111 its process group is sent a
 112 .B SIGTTIN
 113 signal, which suspends the job.
 114 If the
 115 .B TOSTOP
 116 flag has been set for the terminal (see
 117 .BR termios (3)),
 118 then only the foreground job may write to the terminal;
 119 writes from background jobs cause a
 120 .B SIGTTOU
 121 signal to be generated, which suspends the job.
 122 When terminal keys that generate a signal (such as the
 123 .I interrupt
 124 key, normally control-C)
 125 are pressed, the signal is sent to the processes in the foreground job.
 126 .P
 127 Various system calls and library functions
 128 may operate on all members of a process group,
 129 including
 130 .BR kill (2),
 131 .BR killpg (3),
 132 .BR getpriority (2),
 133 .BR setpriority (2),
 134 .BR ioprio_get (2),
 135 .BR ioprio_set (2),
 136 .BR waitid (2),
 137 and
 138 .BR waitpid (2).
 139 See also the discussion of the
 140 .BR F_GETOWN ,
 141 .BR F_GETOWN_EX ,
 142 .BR F_SETOWN ,
 143 and
 144 .B F_SETOWN_EX
 145 operations in
 146 .BR fcntl (2).
 147 .SS User and group identifiers
 148 Each process has various associated user and group IDs.
 149 These IDs are integers, respectively represented using the types
 150 .I uid_t
 151 and
 152 .I gid_t
 153 (defined in
 154 .IR <sys/types.h> ).
 155 .P
 156 On Linux, each process has the following user and group identifiers:
 157 .IP \[bu] 3
 158 Real user ID and real group ID.
 159 These IDs determine who owns the process.
 160 A process can obtain its real user (group) ID using
 161 .BR getuid (2)
 162 .RB ( getgid (2)).
 163 .IP \[bu]
 164 Effective user ID and effective group ID.
 165 These IDs are used by the kernel to determine the permissions
 166 that the process will have when accessing shared resources such
 167 as message queues, shared memory, and semaphores.
 168 On most UNIX systems, these IDs also determine the
 169 permissions when accessing files.
 170 However, Linux uses the filesystem IDs described below
 171 for this task.
 172 A process can obtain its effective user (group) ID using
 173 .BR geteuid (2)
 174 .RB ( getegid (2)).
 175 .IP \[bu]
 176 Saved set-user-ID and saved set-group-ID.
 177 These IDs are used in set-user-ID and set-group-ID programs to save
 178 a copy of the corresponding effective IDs that were set when
 179 the program was executed (see
 180 .BR execve (2)).
 181 A set-user-ID program can assume and drop privileges by
 182 switching its effective user ID back and forth between the values
 183 in its real user ID and saved set-user-ID.
 184 This switching is done via calls to
 185 .BR seteuid (2),
 186 .BR setreuid (2),
 187 or
 188 .BR setresuid (2).
 189 A set-group-ID program performs the analogous tasks using
 190 .BR setegid (2),
 191 .BR setregid (2),
 192 or
 193 .BR setresgid (2).
 194 A process can obtain its saved set-user-ID (set-group-ID) using
 195 .BR getresuid (2)
 196 .RB ( getresgid (2)).
 197 .IP \[bu]
 198 Filesystem user ID and filesystem group ID (Linux-specific).
 199 These IDs, in conjunction with the supplementary group IDs described
 200 below, are used to determine permissions for accessing files; see
 201 .BR path_resolution (7)
 202 for details.
 203 Whenever a process's effective user (group) ID is changed,
 204 the kernel also automatically changes the filesystem user (group) ID
 205 to the same value.
 206 Consequently, the filesystem IDs normally have the same values
 207 as the corresponding effective ID, and the semantics for file-permission
 208 checks are thus the same on Linux as on other UNIX systems.
 209 The filesystem IDs can be made to differ from the effective IDs
 210 by calling
 211 .BR setfsuid (2)
 212 and
 213 .BR setfsgid (2).
 214 .IP \[bu]
 215 Supplementary group IDs.
 216 This is a set of additional group IDs that are used for permission
 217 checks when accessing files and other shared resources.
 218 Before Linux 2.6.4,
 219 a process can be a member of up to 32 supplementary groups;
 220 since Linux 2.6.4,
 221 a process can be a member of up to 65536 supplementary groups.
 222 The call
 223 .I sysconf(_SC_NGROUPS_MAX)
 224 can be used to determine the number of supplementary groups
 225 of which a process may be a member.
 226 .\" Since Linux 2.6.4, the limit is visible via the read-only file
 227 .\" /proc/sys/kernel/ngroups_max.
 228 .\" As at 2.6.22-rc2, this file is still read-only.
 229 A process can obtain its set of supplementary group IDs using
 230 .BR getgroups (2).
 231 .P
 232 A child process created by
 233 .BR fork (2)
 234 inherits copies of its parent's user and groups IDs.
 235 During an
 236 .BR execve (2),
 237 a process's real user and group ID and supplementary
 238 group IDs are preserved;
 239 the effective and saved set IDs may be changed, as described in
 240 .BR execve (2).
 241 .P
 242 Aside from the purposes noted above,
 243 a process's user IDs are also employed in a number of other contexts:
 244 .IP \[bu] 3
 245 when determining the permissions for sending signals (see
 246 .BR kill (2));
 247 .IP \[bu]
 248 when determining the permissions for setting
 249 process-scheduling parameters (nice value, real time
 250 scheduling policy and priority, CPU affinity, I/O priority) using
 251 .BR setpriority (2),
 252 .BR sched_setaffinity (2),
 253 .BR sched_setscheduler (2),
 254 .BR sched_setparam (2),
 255 .BR sched_setattr (2),
 256 and
 257 .BR ioprio_set (2);
 258 .IP \[bu]
 259 when checking resource limits (see
 260 .BR getrlimit (2));
 261 .IP \[bu]
 262 when checking the limit on the number of inotify instances
 263 that the process may create (see
 264 .BR inotify (7)).
 265 .\"
 266 .SS Modifying process user and group IDs
 267 Subject to rules described in the relevant manual pages,
 268 a process can use the following APIs to modify its user and group IDs:
 269 .TP
 270 .BR setuid (2)\~(\c
 271 .BR setgid (2))
 272 Modify the process's real (and possibly effective and saved-set)
 273 user (group) IDs.
 274 .TP
 275 .BR seteuid (2)\~(\c
 276 .BR setegid (2))
 277 Modify the process's effective user (group) ID.
 278 .TP
 279 .BR setfsuid (2)\~(\c
 280 .BR setfsgid (2))
 281 Modify the process's filesystem user (group) ID.
 282 .TP
 283 .BR setreuid (2)\~(\c
 284 .BR setregid (2))
 285 Modify the process's real and effective (and possibly saved-set)
 286 user (group) IDs.
 287 .TP
 288 .BR setresuid (2)\~(\c
 289 .BR setresgid (2))
 290 Modify the process's real, effective, and saved-set user (group) IDs.
 291 .TP
 292 .BR setgroups (2)
 293 Modify the process's supplementary group list.
 294 .P
 295 Any changes to a process's effective user (group) ID
 296 are automatically carried over to the process's
 297 filesystem user (group) ID.
 298 Changes to a process's effective user or group ID can also affect the
 299 process "dumpable" attribute, as described in
 300 .BR prctl (2).
 301 .P
 302 Changes to process user and group IDs can affect the capabilities
 303 of the process, as described in
 304 .BR capabilities (7).
 305 .SH STANDARDS
 306 Process IDs, parent process IDs, process group IDs, and session IDs
 307 are specified in POSIX.1.
 308 The real, effective, and saved set user and groups IDs,
 309 and the supplementary group IDs, are specified in POSIX.1.
 310 .P
 311 The filesystem user and group IDs are a Linux extension.
 312 .SH NOTES
 313 Various fields in the
 314 .IR /proc/ pid /status
 315 file show the process credentials described above.
 316 See
 317 .BR proc (5)
 318 for further information.
 319 .P
 320 The POSIX threads specification requires that
 321 credentials are shared by all of the threads in a process.
 322 However, at the kernel level, Linux maintains separate user and group
 323 credentials for each thread.
 324 The NPTL threading implementation does some work to ensure
 325 that any change to user or group credentials
 326 (e.g., calls to
 327 .BR setuid (2),
 328 .BR setresuid (2))
 329 is carried through to all of the POSIX threads in a process.
 330 See
 331 .BR nptl (7)
 332 for further details.
 333 .SH SEE ALSO
 334 .BR bash (1),
 335 .BR csh (1),
 336 .BR groups (1),
 337 .BR id (1),
 338 .BR newgrp (1),
 339 .BR ps (1),
 340 .BR runuser (1),
 341 .BR setpriv (1),
 342 .BR sg (1),
 343 .BR su (1),
 344 .BR access (2),
 345 .BR execve (2),
 346 .BR faccessat (2),
 347 .BR fork (2),
 348 .BR getgroups (2),
 349 .BR getpgrp (2),
 350 .BR getpid (2),
 351 .BR getppid (2),
 352 .BR getsid (2),
 353 .BR kill (2),
 354 .BR setegid (2),
 355 .BR seteuid (2),
 356 .BR setfsgid (2),
 357 .BR setfsuid (2),
 358 .BR setgid (2),
 359 .BR setgroups (2),
 360 .BR setpgid (2),
 361 .BR setresgid (2),
 362 .BR setresuid (2),
 363 .BR setsid (2),
 364 .BR setuid (2),
 365 .BR waitpid (2),
 366 .BR euidaccess (3),
 367 .BR initgroups (3),
 368 .BR killpg (3),
 369 .BR tcgetpgrp (3),
 370 .BR tcgetsid (3),
 371 .BR tcsetpgrp (3),
 372 .BR group (5),
 373 .BR passwd (5),
 374 .BR shadow (5),
 375 .BR capabilities (7),
 376 .BR namespaces (7),
 377 .BR path_resolution (7),
 378 .BR pid_namespaces (7),
 379 .BR pthreads (7),
 380 .BR signal (7),
 381 .BR system_data_types (7),
 382 .BR unix (7),
 383 .BR user_namespaces (7),
 384 .BR sudo (8)