man7/credentials.7

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