[PATCH v1] landlock: Demonstrate best-effort allowed_access filtering

[Günther Noack]

On Wed, May 13, 2026 at 05:18:53PM +0200, Mickaël Salaün wrote:
> Landlock provides best-effort sandboxing across ABI versions:
> applications request the rights they need, and on older kernels the
> unsupported rights are silently dropped from handled_access_* by the
> documented compatibility switch.  The recommended pattern for
> landlock_add_rule(2) calls is to mirror this filtering at the rule
> level, which wasn't explicitly described in the exemple.
> 
> Show the pattern explicitly in the filesystem and network rule examples
> by masking each rule's allowed_access against the ruleset's
> handled_access_* and adding the rule only when at least one bit remains
> set.  This makes the recommended best-effort pattern self-documenting.
> 
> Signed-off-by: Mickaël Salaün <mic at digikod.net>
> ---
>  Documentation/userspace-api/landlock.rst | 48 +++++++++++++-----------
>  1 file changed, 27 insertions(+), 21 deletions(-)
> 
> diff --git a/Documentation/userspace-api/landlock.rst b/Documentation/userspace-api/landlock.rst
> index fd8b78c31f2f..45861fa75685 100644
> --- a/Documentation/userspace-api/landlock.rst
> +++ b/Documentation/userspace-api/landlock.rst
> @@ -8,7 +8,7 @@ Landlock: unprivileged access control
>  =====================================
>  
>  :Author: Mickaël Salaün
> -:Date: March 2026
> +:Date: May 2026
>  
>  The goal of Landlock is to enable restriction of ambient rights (e.g. global
>  filesystem or network access) for a set of processes.  Because Landlock
> @@ -155,7 +155,7 @@ this file descriptor.
>  
>  .. code-block:: c
>  
> -    int err;
> +    int err = 0;
>      struct landlock_path_beneath_attr path_beneath = {
>          .allowed_access =
>              LANDLOCK_ACCESS_FS_EXECUTE |
> @@ -163,25 +163,29 @@ this file descriptor.
>              LANDLOCK_ACCESS_FS_READ_DIR,
>      };
>  
> -    path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC);
> -    if (path_beneath.parent_fd < 0) {
> -        perror("Failed to open file");
> -        close(ruleset_fd);
> -        return 1;
> -    }
> -    err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH,
> -                            &path_beneath, 0);
> -    close(path_beneath.parent_fd);
> -    if (err) {
> -        perror("Failed to update ruleset");
> -        close(ruleset_fd);
> -        return 1;
> +    path_beneath.allowed_access &= ruleset_attr.handled_access_fs;
> +    if (path_beneath.allowed_access) {
> +        path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC);
> +        if (path_beneath.parent_fd < 0) {
> +            perror("Failed to open file");
> +            close(ruleset_fd);
> +            return 1;
> +        }
> +        err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH,
> +                                &path_beneath, 0);
> +        close(path_beneath.parent_fd);
> +        if (err) {
> +            perror("Failed to update ruleset");
> +            close(ruleset_fd);
> +            return 1;
> +        }
>      }
>  
> -It may also be required to create rules following the same logic as explained
> -for the ruleset creation, by filtering access rights according to the Landlock
> -ABI version.  In this example, this is not required because all of the requested
> -``allowed_access`` rights are already available in ABI 1.
> +As shown above, masking the rule's ``allowed_access`` against the ruleset's
> +``handled_access_*`` is the recommended best-effort pattern: rights the running
> +kernel does not support are dropped (the compatibility switch above already
> +cleared them in ``handled_access_*``), and the rule is skipped if no supported
> +right remains.
>  
>  For network access-control, we can add a set of rules that allow to use a port
>  number for a specific action: HTTPS connections.
> @@ -193,8 +197,10 @@ number for a specific action: HTTPS connections.
>          .port = 443,
>      };
>  
> -    err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT,
> -                            &net_port, 0);
> +    net_port.allowed_access &= ruleset_attr.handled_access_net;
> +    if (net_port.allowed_access)
> +        err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_NET_PORT,
> +                                &net_port, 0);
>  
>  When passing a non-zero ``flags`` argument to ``landlock_restrict_self()``, a
>  similar backwards compatibility check is needed for the restrict flags
> -- 
> 2.54.0
> 

Reviewed-by: Günther Noack <gnoack3000 at gmail.com>

Thanks for the documentation improvement!
–Günther

P.S.: Please don't forget to also transfer this change to the
landlock(7) man page, where we are using the same code example.  I
believe the overlap is mostly in the code there, and the text is
slightly different.