* [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes
@ 2026-11-20 16:11 Günther Noack
2026-11-20 16:11 ` [PATCH v3 1/5] man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just SELinux Günther Noack
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:11 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Günther Noack, linux-man
Hello!
This is patch set (B) spun off from the "Documentation fixes in
unix(7)" patch set [1], which is now split into these three parts:
(A) Miscellaneous fixes, mostly in unix.7, one in socket.7
(B) Socket options and Socket-level Control Messages (SCM_*) <-- this one
(C) sock_diag.7
This patch set fixes unix(7) documentation related to socket options
and SCM_* control messages. The first 5 commits are fixes and factual
corrections, the last two commits are documenting two relevant new
features (PIDFD passing and SO_PASSRIGHTS).
The patch set is based on the "miscellaneous" patch set (A) ("General
Unix Domain Socket fixes"), since it is touching some error code
documentation in the same corner as what is getting changed in (A).
Thank you for your reviews of v1 and v2 of the still-joined patch set,
as well as of v1 of the split patch set.
Changes in v3 (split):
* unix.7: *PIDFD: soften the promise for PIDFDs slightly --
there are cases where it can be missing
* unix.7: SCM_SECURITY: Mention truncation, but do not suggest a
buffer size to use -- that is dependent on LSM.
* Remove already merged commits.
Changes in v2 (split):
* Mention commit hashes in commit messages, not in groff comments
* Reword __scm_send() code snippet in commit message
* s/the last one takes effect/the last one is sent/
* Rewrite SCM_SECURITY section to be about byte buffers
and independent of the LSM
* New commit:
* Remove mentions of "namespace" in the general sense
Changes in v1 (split):
* Some commit message rewording (especially quoted the kernel code
more directly).
* I removed the commit that changed the wording about Out-of-Band
messaging, per Kuniyuki's suggestion in [2].
* The ETOOMANYREFS commit is a SCM_RIGHTS-specific error; the Autobind
documentation change is included here because it refers to
SO_PASSPIDFD.
* I am not 100% happy with how verbose the SCM_SECURITY change has
become, but I don't see a good way to shorten it without cutting
away from the substance.
v1: https://lore.kernel.org/all/20261021212256.27961-1-gnoack3000@gmail.com/
v2: https://lore.kernel.org/all/20261103202211.13820-1-gnoack3000@gmail.com/
–Günther
Günther Noack (5):
man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just
SELinux
man/man7/unix.7: SO_PASSSEC: wfix
man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD
man/man7/unix.7: Document SO_PASSRIGHTS
man/man7/unix.7: Remove mentions of "namespace" in the general sense
man/man7/unix.7 | 169 ++++++++++++++++++++++++++++++++++++++++++++----
1 file changed, 156 insertions(+), 13 deletions(-)
--
2.56.1
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH v3 1/5] man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just SELinux
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
@ 2026-11-20 16:11 ` Günther Noack
2026-11-20 16:11 ` [PATCH v3 2/5] man/man7/unix.7: SO_PASSSEC: wfix Günther Noack
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:11 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Günther Noack, linux-man, Michael Kerrisk, Kuniyuki Iwashima,
Eric Dumazet, Paolo Abeni, Willem de Bruijn
Reword the description of SCM_SECURITY to not be specific to SELinux.
The security context is populated in scm_passec() in linux.git
net/core/scm.c, through the security_secid_to_secctx() LSM hook, which
is currently implemented by SELinux, Smack and AppArmor.
As clarified in [1], the returned security context is in the general
case a byte buffer, not a null-terminated string. The only LSM that
returns a buffer with trailing null byte is SELinux, but even that is
not guaranteed in case that the message is truncated.
Link: [1] <https://lore.kernel.org/all/auZcwYWv0NeiIR8d@google.com/>
Fixes: ffad6a017f91 (2018-07-28; "unix.7: Document SCM_SECURITY ancillary data")
Cc: Michael Kerrisk <mtk.manpages@gmail.com>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Cc: Eric Dumazet <edumazet@kernel.org>
Cc: Paolo Abeni <pabeni@redhat.com>
Cc: Willem de Bruijn <willemb@google.com>
Reported-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
man/man7/unix.7 | 22 ++++++++++++++--------
1 file changed, 14 insertions(+), 8 deletions(-)
diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 61f06a74359b..3322d915f1bb 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -312,7 +312,7 @@ .SS Socket options
is an integer boolean flag.
.TP
.B SO_PASSSEC
-Enables receiving of the SELinux security label of the peer socket
+Enables receiving of the security label of the peer socket
in an ancillary message of type
.B SCM_SECURITY
(see below).
@@ -538,13 +538,19 @@ .SS Ancillary messages
option must be enabled on the socket.
.TP
.B SCM_SECURITY
-Receive the SELinux security context (the security label)
-of the peer socket.
-The received ancillary data is a null-terminated string containing
-the security context.
-The receiver should allocate at least
-.B NAME_MAX
-bytes in the data portion of the ancillary message for this data.
+Receive the security context (the security label)
+of the peer socket,
+as provided by the active Linux Security Module (LSM).
+The received ancillary data is a byte buffer.
+.IP
+The exact format of the security context buffer
+is defined by the active major LSM.
+If the caller does not provide sufficient buffer space,
+the buffer is truncated in a format-unaware manner
+and
+.B MSG_CTRUNC
+is set in
+.IR msg.msg_flags .
.IP
To receive the security context, the
.B SO_PASSSEC
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v3 2/5] man/man7/unix.7: SO_PASSSEC: wfix
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
2026-11-20 16:11 ` [PATCH v3 1/5] man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just SELinux Günther Noack
@ 2026-11-20 16:11 ` Günther Noack
2026-11-20 16:12 ` [PATCH v3 3/5] man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD Günther Noack
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:11 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Günther Noack, linux-man, Kuniyuki Iwashima
Use "security context", as in the description of SCM_SECURITY.
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Assisted-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
man/man7/unix.7 | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 3322d915f1bb..532c50b94ec3 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -312,7 +312,7 @@ .SS Socket options
is an integer boolean flag.
.TP
.B SO_PASSSEC
-Enables receiving of the security label of the peer socket
+Enables receiving of the security context of the peer socket
in an ancillary message of type
.B SCM_SECURITY
(see below).
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v3 3/5] man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
2026-11-20 16:11 ` [PATCH v3 1/5] man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just SELinux Günther Noack
2026-11-20 16:11 ` [PATCH v3 2/5] man/man7/unix.7: SO_PASSSEC: wfix Günther Noack
@ 2026-11-20 16:12 ` Günther Noack
2026-11-20 16:12 ` [PATCH v3 4/5] man/man7/unix.7: Document SO_PASSRIGHTS Günther Noack
2026-11-20 16:12 ` [PATCH v3 5/5] man/man7/unix.7: Remove mentions of "namespace" in the general sense Günther Noack
4 siblings, 0 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:12 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Günther Noack, linux-man, Alexander Mikhalitsyn,
Christian Brauner, Kuniyuki Iwashima, Eric Dumazet
These were added in linux.git 5e2ff6704a27 (2023-06-12; "scm: add
SO_PASSPIDFD and SCM_PIDFD") and 7b26952a91cf (2023-06-12; "net: core:
add getsockopt SO_PEERPIDFD"), both in Linux 6.5. They are the PID
file descriptor counterparts of SO_PASSCRED/SCM_CREDENTIALS and
SO_PEERCRED.
SO_PASSPIDFD
sk_setsockopt() and sk_getsockopt() in net/core/sock.c handle it
as a boolean flag for AF_UNIX sockets (EOPNOTSUPP otherwise).
Like SO_PASSCRED, it triggers autobind, which was already
mentioned in "Autobind feature".
SCM_PIDFD
scm_pidfd_recv() in net/core/scm.c creates the PID file
descriptor from scm->pid, which is the PID given in the sender's
SCM_CREDENTIALS, or the sender's own PID by default. The fd is
created with O_CLOEXEC by pidfd_prepare(). If pidfd_prepare()
fails, its negative error number is put into the cmsg data.
Sending SCM_PIDFD is rejected by __scm_send() (EINVAL).
Since Linux 6.17, with c679d17d3f2d (2025-07-04; "af_unix:
enable handing out pidfds for reaped tasks in SCM_PIDFD"),
PIDFD_STALE is passed, so this also works for reaped processes.
Before that, pidfd_prepare() returned -EINVAL for them.
SO_PEERPIDFD
sk_getsockopt() returns a PID file descriptor for sk_peer_pid,
or fails with ENODATA if there is none.
Since Linux 6.16, with 20b70e58961b (2025-04-28; "net, pidfs:
enable handing out pidfds for reaped sk->sk_peer_pid"), this also
works for reaped processes on AF_UNIX sockets. Before that, it
failed with EINVAL.
Cc: Alexander Mikhalitsyn <alexander@mihalicyn.com>
Cc: Christian Brauner <brauner@kernel.org>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Cc: Eric Dumazet <edumazet@kernel.org>
Assisted-by: LLM
Acked-by: Christian Brauner (Amutable) <brauner@kernel.org>
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
man/man7/unix.7 | 100 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 100 insertions(+)
diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 532c50b94ec3..22fd3b3c6738 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -311,6 +311,32 @@ .SS Socket options
.BR getsockopt (2)
is an integer boolean flag.
.TP
+.BR SO_PASSPIDFD " (since Linux 6.5)"
+Enabling this socket option causes receipt of a PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the sending process in an
+.B SCM_PIDFD
+ancillary message in subsequently received messages
+(see below).
+.IP
+As with
+.BR SO_PASSCRED ,
+when this option is set on a socket that is not bound to an address,
+the socket is autobound to a unique name in the abstract namespace
+when
+.BR connect (2)
+or
+.BR sendmsg (2)
+is called on it;
+see "Autobind feature", below.
+.IP
+The value given as an argument to
+.BR setsockopt (2)
+and returned as the result of
+.BR getsockopt (2)
+is an integer boolean flag.
+.TP
.B SO_PASSSEC
Enables receiving of the security context of the peer socket
in an ancillary message of type
@@ -362,6 +388,43 @@ .SS Socket options
.B AF_UNIX
socket pairs created using
.BR socketpair (2).
+.TP
+.BR SO_PEERPIDFD " (since Linux 6.5)"
+.\" commit 7b26952a91cf65ff1cc867a2382a8964d8c0ee7d
+This read-only socket option returns a new PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the peer process connected to this socket.
+This is the process whose credentials are returned by
+.BR SO_PEERCRED .
+Unlike the PID returned by
+.BR SO_PEERCRED ,
+the PID file descriptor cannot come to refer to a different process
+if the peer process terminates and its PID is reused.
+.IP
+The argument to
+.BR getsockopt (2)
+is a pointer to an
+.IR int ,
+in which the PID file descriptor is returned.
+The close-on-exec flag
+.RB ( FD_CLOEXEC )
+is set on the new file descriptor.
+.IP
+If the socket has no peer process,
+.BR getsockopt (2)
+fails with the error
+.BR ENODATA .
+.IP
+Since Linux 6.16,
+.\" commit 20b70e58961b855e61f2c6a7a19a38a64ad1bed6
+a PID file descriptor is returned
+even if the peer process has already terminated and been reaped.
+Before Linux 6.16,
+.BR getsockopt (2)
+failed with the error
+.B EINVAL
+in this case.
.\"
.SS Autobind feature
If a
@@ -537,6 +600,42 @@ .SS Ancillary messages
.B SO_PASSCRED
option must be enabled on the socket.
.TP
+.BR SCM_PIDFD " (since Linux 6.5)"
+.\" commit 5e2ff6704a275be009be8979af17c52361b79b89
+Receive a PID file descriptor
+(see
+.BR pidfd_open (2))
+referring to the sending process.
+The data portion contains a single
+.IR int .
+The PID file descriptor refers to the process whose PID would be
+received in an
+.B SCM_CREDENTIALS
+message;
+if the sender specified
+.B SCM_CREDENTIALS
+ancillary data,
+it refers to the process with the PID given there.
+The close-on-exec flag
+.RB ( FD_CLOEXEC )
+is set on the new file descriptor.
+.IP
+If the PID file descriptor cannot be created,
+the data portion contains a negative error number instead.
+Since Linux 6.17,
+.\" commit c679d17d3f2d895b34e660673141ad250889831f
+a PID file descriptor is created
+even if the sending process has already terminated and been reaped.
+Before Linux 6.17,
+.B \-EINVAL
+was received in this case.
+.IP
+This message cannot be sent;
+it is generated by the kernel.
+To receive it, the
+.B SO_PASSPIDFD
+option must be enabled on the socket.
+.TP
.B SCM_SECURITY
Receive the security context (the security label)
of the peer socket,
@@ -1255,6 +1354,7 @@ .SS Program source
and
.BR seccomp_unotify (2).
.SH SEE ALSO
+.BR pidfd_open (2),
.BR recvmsg (2),
.BR sendmsg (2),
.BR socket (2),
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v3 4/5] man/man7/unix.7: Document SO_PASSRIGHTS
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
` (2 preceding siblings ...)
2026-11-20 16:12 ` [PATCH v3 3/5] man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD Günther Noack
@ 2026-11-20 16:12 ` Günther Noack
2026-11-20 16:12 ` [PATCH v3 5/5] man/man7/unix.7: Remove mentions of "namespace" in the general sense Günther Noack
4 siblings, 0 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:12 UTC (permalink / raw)
To: Alejandro Colomar
Cc: Günther Noack, linux-man, Kuniyuki Iwashima,
Willem de Bruijn
SO_PASSRIGHTS was added in linux.git 77cbe1a6d873 (2025-05-23;
"af_unix: Introduce SO_PASSRIGHTS."), in Linux 6.16. It lets a
receiver refuse file descriptors passed with SCM_RIGHTS, so that an
untrusted peer cannot leave it with file descriptors whose final
close() blocks for a long time (for example, a file on a hung NFS
mount or a FUSE-controlled file).
The option is enabled by default (unix_create1()). When the receiving
socket has it disabled, unix_dgram_sendmsg(), unix_stream_sendmsg(),
and queue_oob() fail with EPERM if the message carries file
descriptors. The check happens at send time, so messages that are
already queued are unaffected.
Also add the new EPERM case to ERRORS.
Link: [1] <https://uapi-group.org/kernel-features/#disabling-reception-of-scm_rights-for-af_unix-sockets>
Link: [2] <https://lore.kernel.org/all/20250519205820.66184-1-kuniyu@amazon.com/>
Cc: Kuniyuki Iwashima <kuniyu@google.com>
Cc: Willem de Bruijn <willemb@google.com>
Assisted-by: LLM
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
man/man7/unix.7 | 37 +++++++++++++++++++++++++++++++++++++
1 file changed, 37 insertions(+)
diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 22fd3b3c6738..0f014fcb1c40 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -337,6 +337,35 @@ .SS Socket options
.BR getsockopt (2)
is an integer boolean flag.
.TP
+.BR SO_PASSRIGHTS " (since Linux 6.16)"
+.\" commit 77cbe1a6d8730a07f99f9263c2d5f2304cf5e830
+This socket option controls whether the socket accepts
+file descriptors from its peers in
+.B SCM_RIGHTS
+ancillary messages (see below).
+It is enabled by default.
+When it is disabled,
+.BR sendmsg (2)
+calls that pass file descriptors to this socket
+fail with the error
+.BR EPERM .
+The option is checked when the message is sent;
+disabling it does not affect messages
+that are already queued on the socket.
+.IP
+Processes that do not expect to receive file descriptors
+can disable this option.
+Once the file descriptors have been passed,
+closing them is the responsibility of the receiving process,
+and this may block for a long time,
+for example for a file on an unresponsive network file system.
+.IP
+The value given as an argument to
+.BR setsockopt (2)
+and returned as the result of
+.BR getsockopt (2)
+is an integer boolean flag.
+.TP
.B SO_PASSSEC
Enables receiving of the security context of the peer socket
in an ancillary message of type
@@ -874,6 +903,14 @@ .SH ERRORS
specified a datagram socket as the remote address,
but that socket is connected to a different socket.
.TP
+.B EPERM
+The sender passed file descriptors in an
+.B SCM_RIGHTS
+ancillary message,
+but the receiving socket has the
+.B SO_PASSRIGHTS
+option disabled.
+.TP
.B EPIPE
Remote socket was closed on a stream socket.
If enabled, a
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH v3 5/5] man/man7/unix.7: Remove mentions of "namespace" in the general sense
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
` (3 preceding siblings ...)
2026-11-20 16:12 ` [PATCH v3 4/5] man/man7/unix.7: Document SO_PASSRIGHTS Günther Noack
@ 2026-11-20 16:12 ` Günther Noack
4 siblings, 0 replies; 6+ messages in thread
From: Günther Noack @ 2026-11-20 16:12 UTC (permalink / raw)
To: Alejandro Colomar; +Cc: Günther Noack, linux-man, Kuniyuki Iwashima
In unix(7), the word "namespace" is often used in the general sense of
the word, which becomes confusing now that the man page also discusses
its interaction with the Linux namespace concept (see namespaces(7)).
Remove the remaining uses of the word "namespace" in the places where
it is not referring to Linux namespaces.
Reviewed-by: Kuniyuki Iwashima <kuniyu@google.com>
Signed-off-by: Günther Noack <gnoack3000@gmail.com>
---
man/man7/unix.7 | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/man/man7/unix.7 b/man/man7/unix.7
index 0f014fcb1c40..f81611fa2523 100644
--- a/man/man7/unix.7
+++ b/man/man7/unix.7
@@ -24,8 +24,8 @@ .SH DESCRIPTION
efficiently.
Traditionally, UNIX domain sockets can be either unnamed,
or bound to a filesystem pathname (marked as being of type socket).
-Linux also supports an abstract namespace which is independent of the
-filesystem.
+Linux also supports an abstract socket addressing scheme,
+which is independent of the filesystem.
.P
Valid socket types in the UNIX domain are:
.BR SOCK_STREAM ,
@@ -135,7 +135,7 @@ .SS Address format
by the fact that
.I sun_path[0]
is a null byte (\[aq]\[rs]0\[aq]).
-The socket's address in this namespace is given by the additional
+The socket's address is given by the additional
bytes in
.I sun_path
that are covered by the specified length of the address structure.
@@ -297,7 +297,7 @@ .SS Socket options
ancillary data.
.IP
When this option is set on a socket that is not bound to an address,
-the socket is autobound to a unique name in the abstract namespace
+the socket is autobound to a unique abstract socket name
when
.BR connect (2)
or
@@ -323,7 +323,7 @@ .SS Socket options
As with
.BR SO_PASSCRED ,
when this option is set on a socket that is not bound to an address,
-the socket is autobound to a unique name in the abstract namespace
+the socket is autobound to a unique abstract socket name
when
.BR connect (2)
or
@@ -978,7 +978,7 @@ .SH ERRORS
See the appropriate manual pages for more information.
.SH VERSIONS
.B SCM_CREDENTIALS
-and the abstract namespace were introduced with Linux 2.2 and should not
+and abstract sockets were introduced with Linux 2.2 and should not
be used in portable programs.
(Some BSD-derived systems also support credential passing,
but the implementation details differ.)
--
2.56.1
^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2026-11-20 16:12 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2026-11-20 16:11 [PATCH v3 0/5] unix.7: Socket Options and SCM_* fixes Günther Noack
2026-11-20 16:11 ` [PATCH v3 1/5] man/man7/unix.7: SCM_SECURITY: Generalize to other LSMs, not just SELinux Günther Noack
2026-11-20 16:11 ` [PATCH v3 2/5] man/man7/unix.7: SO_PASSSEC: wfix Günther Noack
2026-11-20 16:12 ` [PATCH v3 3/5] man/man7/unix.7: Document SO_PASSPIDFD, SO_PEERPIDFD, and SCM_PIDFD Günther Noack
2026-11-20 16:12 ` [PATCH v3 4/5] man/man7/unix.7: Document SO_PASSRIGHTS Günther Noack
2026-11-20 16:12 ` [PATCH v3 5/5] man/man7/unix.7: Remove mentions of "namespace" in the general sense Günther Noack
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox