diff --git a/docs/content/en/docs/concepts/tracing-policy/hooks.md b/docs/content/en/docs/concepts/tracing-policy/hooks.md index 1d7af55b675..24b14024ba8 100644 --- a/docs/content/en/docs/concepts/tracing-policy/hooks.md +++ b/docs/content/en/docs/concepts/tracing-policy/hooks.md @@ -83,6 +83,187 @@ spec: # [...] ``` +### Lists + +It's possible to define list of functions and use it in the kprobe's `call` field. + +Following example traces all `sys_dup[23]` syscalls. + + +```yaml +spec: + lists: + - name: "dups" + type: "syscalls" + values: + - "sys_dup" + - "sys_dup2" + - "sys_dup3" + kprobes: + - call: "list:dups" +``` + +It is basically a shortcut for following policy: + +```yaml +spec: + kprobes: + - call: "sys_dup" + syscall: true + - call: "sys_dup2" + syscall: true + - call: "sys_dup3" + syscall: true +``` + +As shown in subsequent examples, its main benefit is allowing a single definition for +calls that have the same filters. + +The list is defined under `lists` field with arbitrary values for `name` and `values` fields. + +```yaml +spec: + lists: + - name: "dups" + type: "syscalls" + values: + - "sys_dup" + - "sys_dup2" + - "sys_dup3" + ... +``` + +It's possible to define multiple lists. + +```yaml +spec: + lists: + - name: "dups" + type: "syscalls" + values: + - "sys_dup" + - "sys_dup2" + - "sys_dup3" + name: "another" + - "sys_open" + - "sys_close" +``` + +Specific list can be referenced in kprobe's `call` field with `"list:NAME"` value. + +```yaml +spec: + lists: + - name: "dups" + ... + + kprobes: + - call: "list:dups" +``` + +The kprobe definition creates a kprobe for each item in the list and shares the rest +of the config specified for kprobe. + +List can also specify `type` field that implies extra checks on the values (like for `syscall` type) +or denote that the list is generated automatically (see below). +User must specify `syscall` type for list with syscall functions. Also `syscall` functions +can't be mixed with regular functions in the list. + +The additional selector configuration is shared with all functions in the list. +In following example we create 3 kprobes that share the same pid filter. + + +```yaml +spec: + lists: + - name: "dups" + type: "syscalls" + values: + - "sys_dup" + - "sys_dup2" + - "sys_dup3" + kprobes: + - call: "list:dups" + selectors: + - matchPIDs: + - operator: In + followForks: true + isNamespacePID: false + values: + - 12345 +``` + +It's possible to use argument filter together with the `list`. + +It's important to understand that the argument will be retrieved by using the specified +argument type for all the functions in the list. + +Following example adds argument filter for first argument on all functions in dups list to +match value 9999. + +```yaml +spec: + lists: + - name: "dups" + type: "syscalls" + values: + - "sys_dup" + - "sys_dup2" + - "sys_dup3" + kprobes: + - call: "list:dups" + args: + - index: 0 + type: int + selectors: + - matchArgs: + - index: 0 + operator: "Equal" + values: + - 9999 +``` + +There are two additional special types of generated lists. + +The `generated_syscalls` type of list that generates list with all possible +syscalls on the system. + +Following example traces all syscalls for `/usr/bin/kill` binary. + +```yaml +spec: + lists: + - name: "all-syscalls" + type: "generated_syscalls" + kprobes: + - call: "list:all-syscalls" + selectors: + - matchBinaries: + - operator: "In" + values: + - "/usr/bin/kill" +``` + +The `generated_ftrace` type of list that generates functions from ftrace `available_filter_functions` +file with specified filter. The filter is specified with `pattern` field and expects regular expression. + +Following example traces all kernel `ksys_*` functions for `/usr/bin/kill` binary. + +```yaml +spec: + lists: + - name: "ksys" + type: "generated_ftrace" + pattern: "^ksys_*" + kprobes: + - call: "list:ksys" + selectors: + - matchBinaries: + - operator: "In" + values: + - "/usr/bin/kill" +``` + ## Uprobes {{% pageinfo %}}