man2/landlock_add_rule.2

   1 .\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net>
   2 .\" Copyright © 2019-2020 ANSSI
   3 .\" Copyright © 2021 Microsoft Corporation
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .TH LANDLOCK_ADD_RULE 2 2021-06-27 "Linux man-pages (unreleased)"
   8 .SH NAME
   9 landlock_add_rule \- add a new Landlock rule to a ruleset
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .BR "#include <linux/landlock.h>" "  /* Definition of " LANDLOCK_* " constants */"
  16 .BR "#include <sys/syscall.h>" "     /* Definition of " SYS_* " constants */"
  17 .PP
  18 .BI "int syscall(SYS_landlock_add_rule, int " ruleset_fd ,
  19 .BI "            enum landlock_rule_type " rule_type ,
  20 .BI "            const void *" rule_attr ", uint32_t " flags );
  21 .fi
  22 .SH DESCRIPTION
  23 A Landlock rule describes an action on an object.
  24 An object is currently a file hierarchy,
  25 and the related filesystem actions
  26 are defined with a set of access rights.
  27 This
  28 .BR landlock_add_rule ()
  29 system call enables adding a new Landlock rule to an existing ruleset
  30 created with
  31 .BR landlock_create_ruleset (2).
  32 See
  33 .BR landlock (7)
  34 for a global overview.
  35 .PP
  36 .I ruleset_fd
  37 is a Landlock ruleset file descriptor obtained with
  38 .BR landlock_create_ruleset (2).
  39 .PP
  40 .I rule_type
  41 identifies the structure type pointed to by
  42 .IR rule_attr .
  43 Currently, Linux supports the following
  44 .I rule_type
  45 value:
  46 .TP
  47 .B LANDLOCK_RULE_PATH_BENEATH
  48 This defines the object type as a file hierarchy.
  49 In this case,
  50 .I rule_attr
  51 points to the following structure:
  52 .IP
  53 .in +4n
  54 .EX
  55 struct landlock_path_beneath_attr {
  56     uint64_t  allowed_access;
  57     int32_t   parent_fd;
  58 } __attribute__((packed));
  59 .EE
  60 .in
  61 .IP
  62 .I allowed_access
  63 contains a bitmask of allowed filesystem actions for this file hierarchy
  64 (see
  65 .B Filesystem actions
  66 in
  67 .BR landlock (7)).
  68 .IP
  69 .I parent_fd
  70 is an opened file descriptor, preferably with the
  71 .I O_PATH
  72 flag,
  73 which identifies the parent directory of the file hierarchy or
  74 just a file.
  75 .PP
  76 .I flags
  77 must be 0.
  78 .SH RETURN VALUE
  79 On success,
  80 .BR landlock_add_rule ()
  81 returns 0.
  82 .SH ERRORS
  83 .BR landlock_add_rule ()
  84 can failed for the following reasons:
  85 .TP
  86 .B EOPNOTSUPP
  87 Landlock is supported by the kernel but disabled at boot time.
  88 .TP
  89 .B EINVAL
  90 .I flags
  91 is not 0, or the rule accesses are inconsistent (i.e.,
  92 .I rule_attr->allowed_access
  93 is not a subset of the ruleset handled accesses).
  94 .TP
  95 .B ENOMSG
  96 Empty accesses (i.e.,
  97 .I rule_attr->allowed_access
  98 is 0).
  99 .TP
 100 .B EBADF
 101 .I ruleset_fd
 102 is not a file descriptor for the current thread,
 103 or a member of
 104 .I rule_attr
 105 is not a file descriptor as expected.
 106 .TP
 107 .B EBADFD
 108 .I ruleset_fd
 109 is not a ruleset file descriptor,
 110 or a member of
 111 .I rule_attr
 112 is not the expected file descriptor type.
 113 .TP
 114 .B EPERM
 115 .I ruleset_fd
 116 has no write access to the underlying ruleset.
 117 .TP
 118 .B EFAULT
 119 .I rule_attr
 120 was not a valid address.
 121 .SH VERSIONS
 122 Landlock was added in Linux 5.13.
 123 .SH STANDARDS
 124 This system call is Linux-specific.
 125 .SH EXAMPLES
 126 See
 127 .BR landlock (7).
 128 .SH SEE ALSO
 129 .BR landlock_create_ruleset (2),
 130 .BR landlock_restrict_self (2),
 131 .BR landlock (7)