[PATCH] docs: landlock: clarify TTY signal scoping

[PATCH] docs: landlock: clarify TTY signal scoping

[Christopher Lusk]

LANDLOCK_SCOPE_SIGNAL mediates signal delivery when a sandboxed process
selects the recipient, including SIGIO through fowner.  It does not mediate
signals directed by the TTY layer to processes attached to a terminal in
response to terminal activity.  This distinction was clarified while
discussing TIOCSIG handling because the PTY master acts as a capability and
the signal recipients have attached to the terminal.

Document the TTY-driven signal paths which are outside the scope and advise
controlling access to the terminal or PTY master instead.  This records the
outcome of the RFC discussion and avoids implying that
LANDLOCK_SCOPE_SIGNAL covers every signal-delivery mechanism.

The documentation text and changelog were drafted with assistance from
Claude (claude-opus-4-8) and Codex (gpt-5.6-sol).

The userspace API documentation builds successfully with the kernel-pinned
Sphinx dependencies.  The remaining warnings are unrelated to the changed
Landlock text.

Link: https://lore.kernel.org/r/20260914.b8a029f9abb8@gnoack.org
Suggested-by: Günther Noack <gnoack@google.com>
Assisted-by: Claude:claude-opus-4-8
Assisted-by: Codex:gpt-5.6-sol
Signed-off-by: Christopher Lusk <clusk@northecho.dev>
---
 Documentation/userspace-api/landlock.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
index 84cb7bf6b3ed..64418b09840d 100644
--- a/Documentation/userspace-api/landlock.rst
+++ b/Documentation/userspace-api/landlock.rst
@@ -430,6 +430,21 @@ The operations which can be scoped are:
     This limits the sending of signals to target processes which run within the
     same or a nested Landlock domain.
 
+    This scope does not cover signals delivered by the TTY layer.  A process
+    holding a PTY master, or otherwise driving a terminal, can cause the TTY
+    driver to deliver signals to processes attached to that terminal across
+    Landlock domain boundaries.  This includes ``SIGINT``, ``SIGQUIT``, and
+    ``SIGTSTP`` via the ``TIOCSIG`` :manpage:`ioctl(2)` command or the
+    corresponding control characters.  The TTY layer may also deliver
+    ``SIGWINCH``, ``SIGHUP``, and ``SIGCONT``.
+
+    These signals originate from the TTY driver in response to terminal
+    activity rather than from a :manpage:`kill(2)`-style request.  They can
+    only reach processes attached to the terminal.  To restrict this
+    interaction, control possession of the PTY master and terminal attachment.
+    For example, do not pass a PTY master to a sandboxed process if its slave
+    has processes from outside the Landlock domain attached to it.
+
 ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
     This limits the set of abstract :manpage:`unix(7)` sockets to which we can
     :manpage:`connect(2)` to socket addresses which were created by a process in
-- 
2.55.0

Re: [PATCH] docs: landlock: clarify TTY signal scoping

[Günther Noack]

Hello!

Thanks for the review!

On Mon, Sep 14, 2026 at 02:09:46PM -0400, Christopher Lusk wrote:
> LANDLOCK_SCOPE_SIGNAL mediates signal delivery when a sandboxed process
> selects the recipient, including SIGIO through fowner.  It does not mediate
> signals directed by the TTY layer to processes attached to a terminal in
> response to terminal activity.  This distinction was clarified while
> discussing TIOCSIG handling because the PTY master acts as a capability and
> the signal recipients have attached to the terminal.
> 
> Document the TTY-driven signal paths which are outside the scope and advise
> controlling access to the terminal or PTY master instead.  This records the
> outcome of the RFC discussion and avoids implying that
> LANDLOCK_SCOPE_SIGNAL covers every signal-delivery mechanism.
> 
> The documentation text and changelog were drafted with assistance from
> Claude (claude-opus-4-8) and Codex (gpt-5.6-sol).
> 
> The userspace API documentation builds successfully with the kernel-pinned
> Sphinx dependencies.  The remaining warnings are unrelated to the changed
> Landlock text.
> 
> Link: https://lore.kernel.org/r/20260914.b8a029f9abb8@gnoack.org
> Suggested-by: Günther Noack <gnoack@google.com>
> Assisted-by: Claude:claude-opus-4-8
> Assisted-by: Codex:gpt-5.6-sol
> Signed-off-by: Christopher Lusk <clusk@northecho.dev>
> ---
>  Documentation/userspace-api/landlock.rst | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index 84cb7bf6b3ed..64418b09840d 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -430,6 +430,21 @@ The operations which can be scoped are:
>      This limits the sending of signals to target processes which run within the
>      same or a nested Landlock domain.
>  
> +    This scope does not cover signals delivered by the TTY layer.  A process
> +    holding a PTY master, or otherwise driving a terminal, can cause the TTY
                             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

What other ways of driving a terminal are you alluding to?  (I assume
the LLM wrote that?  Did it make that up, or does it have another trick
up its sleeve for sending signals that we are overlooking?)


> +    driver to deliver signals to processes attached to that terminal across
> +    Landlock domain boundaries.  This includes ``SIGINT``, ``SIGQUIT``, and
> +    ``SIGTSTP`` via the ``TIOCSIG`` :manpage:`ioctl(2)` command or the
> +    corresponding control characters.  The TTY layer may also deliver
> +    ``SIGWINCH``, ``SIGHUP``, and ``SIGCONT``.
> +
> +    These signals originate from the TTY driver in response to terminal
> +    activity rather than from a :manpage:`kill(2)`-style request.  They can
> +    only reach processes attached to the terminal.  To restrict this
> +    interaction, control possession of the PTY master and terminal attachment.
> +    For example, do not pass a PTY master to a sandboxed process if its slave
> +    has processes from outside the Landlock domain attached to it.
> +

LANDLOCK_SCOPE_SIGNAL was previously described in two lines here.
Now we have 15 lines, 13 of which are talking exclusively about the PTY corner
case.  I am afraid this will water down the main message here.

I understand that LLMs can help in writing good English, but they also
have a tendency to be much more verbose than the existing text and can
direct the reader's attention away from the main points with that.

Suggested replacement:

  Holding a PTY master FD still grants the capability to issue signals
  through that PTY to the processes running under that terminal.

Does that seem reasonable?

Listing the full list of signals that can be sent through a PTY seems like an
excessive level of detail here.  But if you find a reference listing
the same signals in kernel doc or a stable URL, we could link it from
the docs.


Please also add an (even shorter) remark to the landlock.h header
file's description of LANDLOCK_SCOPE_SIGNAL, similar in length to the
one we added for the whiteout objects for LANDLOCK_ACCESS_FS_MAKE_REG
recently.

>  ``LANDLOCK_SCOPE_ABSTRACT_UNIX_SOCKET``
>      This limits the set of abstract :manpage:`unix(7)` sockets to which we can
>      :manpage:`connect(2)` to socket addresses which were created by a process in
> -- 
> 2.55.0
> 

Some meta-level remarks:

* Please send new patch sets as top-level emails rather than as
  responses to existing mail threads.  (It is not technically wrong to
  do that, but they do get overlooked within mail threads more often.
  To connect the dots, you can link the original mail on lore as
  you've already done here as well.)

* *If you want*, a thing that would still be worthwhile having in code
  would be a regression selftest for this signal sending path.  This
  is similar to the tests you've already created in your initial
  patchset, but would now check that signal sending *works* despite
  the sender being in the scoped domain.

(For transparency, I should remark that the final decision on this
code review is still up to Mickaël in the end.  I do believe that this
approach is the best solution, but the reasoning is less clear-cut
than in other bugs we had before.)

Thanks,
—Günther

Re: [PATCH] docs: landlock: clarify TTY signal scoping

[Christopher Lusk]

Hello Günther,

Thank you for the careful review.

The phrase "or otherwise driving a terminal" was LLM over-generalization,
not a separate mechanism.  I checked the paths I had in mind against the
source, and none justifies that broader wording.  I am dropping it.

You are also right about the verbosity.  The generated text expanded a
two-line distinction into 15 lines and obscured the main point.  I will use
your suggested sentence and remove the signal enumeration.  I do not have a
stable kernel documentation URL for that list, so I will not add a citation.

v2 will contain your sentence and a short LANDLOCK_SCOPE_SIGNAL remark in
landlock.h, matched to the recent MAKE_REG whiteout remark.  I will post it
as a new top-level patch with a Link back to this discussion.

I will keep the positive selftest you suggested as a separate follow-up so
the documentation clarification can be reviewed independently.

Christopher

Re: [PATCH] docs: landlock: clarify TTY signal scoping

[Günther Noack]

On Wed, Sep 16, 2026 at 10:52:55AM -0400, Christopher Lusk wrote:
> Hello Günther,
> 
> Thank you for the careful review.
> 
> The phrase "or otherwise driving a terminal" was LLM over-generalization,
> not a separate mechanism.  I checked the paths I had in mind against the
> source, and none justifies that broader wording.  I am dropping it.

Thanks for double checking the wording, sounds good.

        
> You are also right about the verbosity.  The generated text expanded a
> two-line distinction into 15 lines and obscured the main point.  I will use
> your suggested sentence and remove the signal enumeration.  I do not have a
> stable kernel documentation URL for that list, so I will not add a citation.
> 
> v2 will contain your sentence and a short LANDLOCK_SCOPE_SIGNAL remark in
> landlock.h, matched to the recent MAKE_REG whiteout remark.  I will post it
> as a new top-level patch with a Link back to this discussion.
> 
> I will keep the positive selftest you suggested as a separate follow-up so
> the documentation clarification can be reviewed independently.

Sounds good as well.

—Günther