path: root/man5/proc.5

.\" Copyright (C) 1994, 1995, Daniel Quinlan <quinlan@yggdrasil.com>
.\" Copyright (C) 2002-2008, 2017, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright (C) 2023, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: GPL-3.0-or-later
.\"
.TH proc 5 2023-10-31 "Linux man-pages 6.7"
.SH NAME
proc \- process information, system information, and sysctl pseudo-filesystem
.SH DESCRIPTION
The
.B proc
filesystem is a pseudo-filesystem which provides an interface to
kernel data structures.
It is commonly mounted at
.IR /proc .
Typically, it is mounted automatically by the system,
but it can also be mounted manually using a command such as:
.P
.in +4n
.EX
mount \-t proc proc /proc
.EE
.in
.P
Most of the files in the
.B proc
filesystem are read-only,
but some files are writable, allowing kernel variables to be changed.
.\"
.SS Mount options
The
.B proc
filesystem supports the following mount options:
.TP
.BR hidepid "=\fIn\fP (since Linux 3.3)"
.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201
This option controls who can access the information in
.IR /proc/ pid
directories.
The argument,
.IR n ,
is one of the following values:
.RS
.TP 4
0
Everybody may access all
.IR /proc/ pid
directories.
This is the traditional behavior,
and the default if this mount option is not specified.
.TP
1
Users may not access files and subdirectories inside any
.IR /proc/ pid
directories but their own (the
.IR /proc/ pid
directories themselves remain visible).
Sensitive files such as
.IR /proc/ pid /cmdline
and
.IR /proc/ pid /status
are now protected against other users.
This makes it impossible to learn whether any user is running a
specific program
(so long as the program doesn't otherwise reveal itself by its behavior).
.\" As an additional bonus, since
.\" .IR /proc/[pid]/cmdline
.\" is inaccessible for other users,
.\" poorly written programs passing sensitive information via
.\" program arguments are now protected against local eavesdroppers.
.TP
2
As for mode 1, but in addition the
.IR /proc/ pid
directories belonging to other users become invisible.
This means that
.IR /proc/ pid
entries can no longer be used to discover the PIDs on the system.
This doesn't hide the fact that a process with a specific PID value exists
(it can be learned by other means, for example, by "kill \-0 $PID"),
but it hides a process's UID and GID,
which could otherwise be learned by employing
.BR stat (2)
on a
.IR /proc/ pid
directory.
This greatly complicates an attacker's task of gathering
information about running processes (e.g., discovering whether
some daemon is running with elevated privileges,
whether another user is running some sensitive program,
whether other users are running any program at all, and so on).
.RE
.TP
.BR gid "=\fIgid\fP (since Linux 3.3)"
.\" commit 0499680a42141d86417a8fbaa8c8db806bea1201
Specifies the ID of a group whose members are authorized to
learn process information otherwise prohibited by
.B hidepid
(i.e., users in this group behave as though
.I /proc
was mounted with
.IR hidepid=0 ).
This group should be used instead of approaches such as putting
nonroot users into the
.BR sudoers (5)
file.
.\"
.SS Overview
Underneath
.IR /proc ,
there are the following general groups of files and subdirectories:
.TP
.IR /proc/ "pid subdirectories"
Each one of these subdirectories contains files and subdirectories
exposing information about the process with the corresponding process ID.
.IP
Underneath each of the
.IR /proc/ pid
directories, a
.I task
subdirectory contains subdirectories of the form
.IR task/ tid,
which contain corresponding information about each of the threads
in the process, where
.I tid
is the kernel thread ID of the thread.
.IP
The
.IR /proc/ pid
subdirectories are visible when iterating through
.I /proc
with
.BR getdents (2)
(and thus are visible when one uses
.BR ls (1)
to view the contents of
.IR /proc ).
.TP
.IR /proc/ "tid subdirectories"
Each one of these subdirectories contains files and subdirectories
exposing information about the thread with the corresponding thread ID.
The contents of these directories are the same as the corresponding
.IR /proc/ pid /task/ tid
directories.
.IP
The
.IR /proc/ tid
subdirectories are
.I not
visible when iterating through
.I /proc
with
.BR getdents (2)
(and thus are
.I not
visible when one uses
.BR ls (1)
to view the contents of
.IR /proc ).
.TP
.I /proc/self
When a process accesses this magic symbolic link,
it resolves to the process's own
.IR /proc/ pid
directory.
.TP
.I /proc/thread\-self
When a thread accesses this magic symbolic link,
it resolves to the process's own
.IR /proc/self/task/ tid
directory.
.TP
.I /proc/[a\-z]*
Various other files and subdirectories under
.I /proc
expose system-wide information.
.P
All of the above are described in more detail below.
.\"
.\" .SH FILES
.\" FIXME Describe /proc/[pid]/sessionid
.\"	  commit 1e0bd7550ea9cf474b1ad4c6ff5729a507f75fdc
.\"       CONFIG_AUDITSYSCALL
.\"       Added in Linux 2.6.25; read-only; only readable by real UID
.\"
.\" FIXME Describe /proc/[pid]/sched
.\"       Added in Linux 2.6.23
.\"       CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS
.\"       Displays various scheduling parameters
.\"       This file can be written, to reset stats
.\"       The set of fields exposed by this file have changed
.\"	  significantly over time.
.\"       commit 43ae34cb4cd650d1eb4460a8253a8e747ba052ac
.\"
.\" FIXME Describe /proc/[pid]/schedstats and
.\"       /proc/[pid]/task/[tid]/schedstats
.\"       Added in Linux 2.6.9
.\"       CONFIG_SCHEDSTATS
.\" FIXME Document /proc/sched_debug (since Linux 2.6.23)
.\" See also /proc/[pid]/sched
.\" FIXME 2.6.13 seems to have /proc/vmcore implemented; document this
.\" 	See Documentation/kdump/kdump.txt
.\"	commit 666bfddbe8b8fd4fd44617d6c55193d5ac7edb29
.\" 	Needs CONFIG_VMCORE
.\"
.SH NOTES
Many files contain strings (e.g., the environment and command line)
that are in the internal format,
with subfields terminated by null bytes (\[aq]\e0\[aq]).
When inspecting such files, you may find that the results are more readable
if you use a command of the following form to display them:
.P
.in +4n
.EX
.RB "$" " cat \fIfile\fP | tr \[aq]\e000\[aq] \[aq]\en\[aq]"
.EE
.in
.\" .SH ACKNOWLEDGEMENTS
.\" The material on /proc/sys/fs and /proc/sys/kernel is closely based on
.\" kernel source documentation files written by Rik van Riel.
.SH SEE ALSO
.BR cat (1),
.BR dmesg (1),
.BR find (1),
.BR free (1),
.BR htop (1),
.BR init (1),
.BR ps (1),
.BR pstree (1),
.BR tr (1),
.BR uptime (1),
.BR chroot (2),
.BR mmap (2),
.BR readlink (2),
.BR syslog (2),
.BR slabinfo (5),
.BR sysfs (5),
.BR hier (7),
.BR namespaces (7),
.BR time (7),
.BR arp (8),
.BR hdparm (8),
.BR ifconfig (8),
.BR lsmod (8),
.BR lspci (8),
.BR mount (8),
.BR netstat (8),
.BR procinfo (8),
.BR route (8),
.BR sysctl (8)
.P
The Linux kernel source files:
.IR Documentation/filesystems/proc.rst ,
.IR Documentation/admin\-guide/sysctl/fs.rst ,
.IR Documentation/admin\-guide/sysctl/kernel.rst ,
.IR Documentation/admin\-guide/sysctl/net.rst ,
and
.IR Documentation/admin\-guide/sysctl/vm.rst .