documentation: more detailed description re FollowFD/UnfollowFD #2228
Conversation
christian-2
commented
Mar 15, 2024
christian-2
commented
- a first stab of what was discussed on w/ @kevsecurity , @mtardy on Slack
✅ Deploy Preview for tetragon ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
mtardy
added
area/documentation
| The `fd_install` kernel function is called each time a file descriptor must be | ||
| installed into the file descriptor table of a process, typically referenced | ||
| within system calls like `open` or `openat`. It is a good place for tracking | ||
| file descriptor and filename matching. | ||
| `FollowFD` is typically used at hook points where a file descriptor and its | ||
| associated file name appear together. The kernel function `fd_install` | ||
| is a case in point. |
There was a problem hiding this comment.
I'm not sure I get the replacement here, do you think what was said on fd_install was wrong?
There was a problem hiding this comment.
No, I just thought the mentioning of a processes file descriptor table might cause confusion opposite the eBPF table where Tetragon keeps associations between file descriptors and file names. I'll put the earlier sentence back in.
| While the mapping between the file descriptor and file name remains in place | ||
| (i.e. between `FollowFD` and `UnfollowFD` for the same file descriptor) tracing | ||
| policies may refer to file names where file descriptors | ||
| would otherwise have to serve instead. This offers greater convenience and |
There was a problem hiding this comment.
I get the meaning here but the "have to serve instead" is a bit difficult to understand. Maybe we can simplify "tracing policies may refer to file names instead of file descriptors"?
There was a problem hiding this comment.
Yes, I have no issue with that.
| `/etc/passwd`. The system call `sys_write` only receives a file descriptor | ||
| (not a file name) as argument. Yet with a bracketing pair for `FollowFD` |
There was a problem hiding this comment.
| `/etc/passwd`. The system call `sys_write` only receives a file descriptor | |
| (not a file name) as argument. Yet with a bracketing pair for `FollowFD` | |
| `/etc/passwd`. The system call `sys_write` only receives a file descriptor, | |
| not a file name, as an argument. Yet with a bracketing pair for `FollowFD` |
| `/etc/passwd`. The system call `sys_write` only receives a file descriptor | ||
| (not a file name) as argument. Yet with a bracketing pair for `FollowFD` |
There was a problem hiding this comment.
What do you mean by "bracketing pair"?
There was a problem hiding this comment.
I am using a metaphor that compares FollowFD and UnfollowFD to an opening and closing bracket, respectively. The reference to a file name appears in between, like an element between two brackets in mathematical set notation; hence the pair consisting of FollowFD and UnfollowFD is bracketing the reference to the file name, so to speak. Is it clearer now?
| file descriptor and filename matching. | ||
| `FollowFD` is typically used at hook points where a file descriptor and its | ||
| associated file name appear together. The kernel function `fd_install` | ||
| is a case in point. |
There was a problem hiding this comment.
I think it's my English but I never saw in my life "a case in point" in a documentation 😸
There was a problem hiding this comment.
FWIK "a case in point" is synonymous with "a good example of". I can use the second, no problem.
|
@mtardy Thanks for your careful review. I'll submit another version according to my earlier replies. @kevsecurity Thanks for your approval. Please (both of you) let me know if you have further comments. |
| descriptors and filenames. It however needs to maintain a state | ||
| correctly, see [`UnfollowFD`](#unfollowfd-action) and | ||
| [`CopyFD`](#copyfd-action) related actions. |
There was a problem hiding this comment.
| descriptors and filenames. It however needs to maintain a state | |
| correctly, see [`UnfollowFD`](#unfollowfd-action) and | |
| [`CopyFD`](#copyfd-action) related actions. | |
| descriptors and filenames. After its creation, the mapping can be maintained via [`UnfollowFD`](#unfollowfd-action) and [`CopyFD`](#copyfd-action) actions. Note that proper maintenance of the mapping is up to the tracing policy writer. |
| @@ -682,11 +686,79 @@ This action uses the dedicated `argFd` and `argName` fields to get respectively | |||
| the index of the file descriptor argument and the index of the name argument in | |||
| the call. | |||
|
|
|||
| While the mapping between the file descriptor and file name remains in place | |||
| (i.e. between `FollowFD` and `UnfollowFD` for the same file descriptor) tracing | |||
There was a problem hiding this comment.
| (i.e. between `FollowFD` and `UnfollowFD` for the same file descriptor) tracing | |
| (that is, between `FollowFD` and `UnfollowFD` for the same file descriptor) tracing |
note: we generally try to avoid use of latin abbreviations. See: https://docs.cilium.io/en/stable/contributing/docs/docsstyle/#don-t-use-latin-abbreviations.
|
@kkourt Thanks also for your review. I'm fine with these changes, plus: I replaced "via" (another Latin term) by "through" and "file name" by "filename" (the latter appears to be the more frequent spelling in the surrounding material.) |
|
Keep in mind that you can re-request a review by clicking on the github button "Re-request review".
|
|
I wanted to just merge this but could you remove the leading "*" in the commit title, I'm wondering if it can create weird stuff when we list the commits then. Maybe replace with docs: or just remove the star :) thanks, sorry for this last nit |
Signed-off-by: Christian Hörtnagl <christian2@univie.ac.at>
|
@mtardy re PR: you are welcome; re no star: you are right, I was following a local convention by habit (now fixed) |
