Re: [PATCH v2 1/4] landlock.7: Add a new page to introduce Landlock

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Hi Mickaël,

On 7/30/21 2:41 PM, Alejandro Colomar (man-pages) wrote:
[...]



I hope this was helpful :)

Cheers,

Alex




But, let's use .I

I hit send too soon.  Let's continue.

As for current usage, yes, there are many uses of .IR to mean .I, but for new code, we're only using .I (or .B) when possible.



CC: Branden



If there was a misunderstanding about this, I'm sorry.

* Append punctuation to ".IR" and ".BR" when it makes sense (requested
    by Alejandro Colomar).
* Cut lines according to the semantic newline rules (requested by
    Alejandro Colomar).
* Remove roman style from ".TP" section titles (requested by Alejandro
    Colomar).
* Add comma after "i.e." and "e.g.".
* Move the example in a new EXAMPLES section.
* Improve title.
* Explain the LSM acronym at first use.
---
   man7/landlock.7 | 356 ++++++++++++++++++++++++++++++++++++++++++++++++
   1 file changed, 356 insertions(+)
   create mode 100644 man7/landlock.7

diff --git a/man7/landlock.7 b/man7/landlock.7
new file mode 100644
index 000000000000..c89f5b1cabb6
--- /dev/null
+++ b/man7/landlock.7
@@ -0,0 +1,356 @@
+.\" Copyright © 2017-2020 Mickaël Salaün <mic@xxxxxxxxxxx>
+.\" Copyright © 2019-2020 ANSSI
+.\" Copyright © 2021 Microsoft Corporation
+.\"
+.\" %%%LICENSE_START(VERBATIM)
+.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of
this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.\"
+.\" Since the Linux kernel and libraries are constantly changing, this
+.\" manual page may be incorrect or out-of-date.  The author(s)
assume no
+.\" responsibility for errors or omissions, or for damages resulting
from
+.\" the use of the information contained herein.  The author(s) may not +.\" have taken the same level of care in the production of this manual,
+.\" which is licensed free of charge, as they might when working
+.\" professionally.
+.\"
+.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work.
+.\" %%%LICENSE_END
+.\"
+.TH LANDLOCK 7 2021-06-27 Linux "Linux Programmer's Manual"
+.SH NAME
+Landlock \- unprivileged access-control
+.SH DESCRIPTION
+Landlock is an access-control system that enables any processes to //
securely /J/

Why adding a line break here? This line is 75 columns as stated by the
documentation: https://man7.org/linux/man-pages/man7/man-pages.7.html
I guess it helps for semantic newlines, right? If so, what are the rules?

Yes, they were because of semantic newlines.

The "rules" are:

Follow mainly "semantic newlines" style (forgetting about the line length), which will give you a text that (mostly) fits into 75 or 80 columns.

If after doing that there are some lines that exceed the 75 or 80 column right margin, consider fixing that line by breaking it at a different point or maybe breaking it further. The 80 column limit is a hard limit (I can't read anything past the 80 col), while the 75 limit is a bit softer (that's for allowing quotes in reviews) (if fitting a line into col 75 would break it in a weird way, don't do it).

If I didn't explain myself enough, please tell me.

+upper layer.
+From a Landlock policy point of view,
+each OverlayFS layers and merge hierarchies are standalone and contains
+their own set of files and directories,
+which is different from bind mounts.


Incorrect mix of singular and plural, I think.
>> Is it OK with s/contains/contain/?

I think so.



+A policy restricting an OverlayFS layer will not restrict the resulted
+merged hierarchy, and vice versa.
+Landlock users should then only think about file hierarchies they
want to
+allow access to, regardless of the underlying filesystem.
+.\"
+.SS Inheritance
+Every new thread resulting from a
+.BR clone (2)
+inherits Landlock domain restrictions from its parent.
+This is similar to the
+.BR seccomp (2)
+inheritance or any other LSM dealing with task's

Not sure:

s/task/a task/
or
s/task's/tasks'/

I'll take "tasks'".

Okay.



+.BR credentials (7).
+For instance, one process's thread may apply Landlock rules to itself,

s/process's/process'/

As pointed out by Branden, this is correct.

That's right. :)



+.BR chdir (2),
+.BR truncate (2),
+.BR stat (2),
+.BR flock (2),
+.BR chmod (2),
+.BR chown (2),
+.BR setxattr (2),
+.BR utime (2),
+.BR ioctl (2),
+.BR fcntl (2),
+.BR access (2).
+Future Landlock evolutions will enable to restrict them.
+.SH EXAMPLES
I'd prefer a complete example with a main function, if you can come up
with such one.  If not, this will be ok.

I think it is clearer to not to use a full main to explain these basic
steps. A full working example is linked though.

Ahh sorry, I didn't see the link.
I'll have a look at it.




+We first need to create the ruleset that will contain our rules.
+For this example,
+the ruleset will contain rules that only allow read actions,
+but write actions will be denied.
+The ruleset then needs to handle both of these kind of actions.
+See below for the description of filesystem actions.
+.PP
+.in +4n
+.EX
+int ruleset_fd;
+struct landlock_ruleset_attr ruleset_attr = {
+    .handled_access_fs =
+        LANDLOCK_ACCESS_FS_EXECUTE |
+        LANDLOCK_ACCESS_FS_WRITE_FILE |
+        LANDLOCK_ACCESS_FS_READ_FILE |
+        LANDLOCK_ACCESS_FS_READ_DIR |
+        LANDLOCK_ACCESS_FS_REMOVE_DIR |
+        LANDLOCK_ACCESS_FS_REMOVE_FILE |
+        LANDLOCK_ACCESS_FS_MAKE_CHAR |
+        LANDLOCK_ACCESS_FS_MAKE_DIR |
+        LANDLOCK_ACCESS_FS_MAKE_REG |
+        LANDLOCK_ACCESS_FS_MAKE_SOCK |
+        LANDLOCK_ACCESS_FS_MAKE_FIFO |
+        LANDLOCK_ACCESS_FS_MAKE_BLOCK |
+        LANDLOCK_ACCESS_FS_MAKE_SYM,
+};
+
+ruleset_fd = landlock_create_ruleset(&ruleset_attr,
sizeof(ruleset_attr), 0);
+if (ruleset_fd < 0) {
+    perror("Failed to create a ruleset");
+    return 1;
+}
+.EE
+.in
+.PP
+We can now add a new rule to this ruleset thanks to the returned file
+descriptor referring to this ruleset.
+The rule will only allow reading the file hierarchy
+.IR /usr .

Why ".IR" is correct here?

"/usr" needs to be formatted, but "." not.

[
.I /usr
.
]

Would add a space: /usr .
So we need a solution that formats only part of a space-separated token; that's what .IR does. I hope the last email explained that well.

Thanks,

Alex


--
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/



[Index of Archives]     [Kernel Documentation]     [Netdev]     [Linux Ethernet Bridging]     [Linux Wireless]     [Kernel Newbies]     [Security]     [Linux for Hams]     [Netfilter]     [Bugtraq]     [Yosemite News]     [MIPS Linux]     [ARM Linux]     [Linux RAID]     [Linux Admin]     [Samba]

  Powered by Linux