CRD: add documentation for maxData and returnCopy flag

Also enrich the TracingPolicy reference documentation about these flags.

Signed-off-by: Mahe Tardy <[email protected]>

docs/content/en/docs/reference/tracing-policy.md

@@ -243,22 +243,28 @@ The indexing starts with 0. So, `index: 0` means, this is going to be the first
 argument of the function, `index: 1` means this is going to be the second
 argument of the function, etc.
 
-Note that for some args types, `char_buf` and `char_iovec`, there is an
-additional field named `returnCopy` and a `sizeArgIndex` field to specify to
-use one of the arguments to read the buffer correctly from the BPF code.
-
-This is the length that the BPF program is looking for in order to read the
-`char_buf`. So, `size_t` is the number of `char_buf` elements stored in the
-pointer of the second argument. Similarly, if we would like to capture the the
-`__x64_sys_writev(long, iovec *, vlen)` syscall, then `iovec` has a size of
-`vlen`, which is going to be the 3rd argument.
+Note that for some args types, `char_buf` and `char_iovec`, there are
+additional fields named `returnCopy` and `sizeArgIndex` available:
+- `returnCopy` indicates that the corresponding argument should be read later (when
+  the kretprobe for the symbol is triggered) because it might not be populated
+  when the kprobe is triggered at the entrance of the function. For example, a
+  buffer supplied to `read(2)` won't have content until kretprobe is triggered.
+- `sizeArgIndex` indicates the (1-based, see warning below) index of the arguments
+  that represents the size of the `char_buf` or `iovec`. For example, for
+  `write(2)`, the third argument, `size_t count` is the number of `char`
+  element that we can read from the `const void *buf` pointer from the second
+  argument. Similarly, if we would like to capture the `__x64_sys_writev(long,
+  iovec *, vlen)` syscall, then `iovec` has a size of `vlen`, which is going to
+  be the third argument.
 
 {{< caution >}}
 `sizeArgIndex` is inconsistent at the moment and does not take the index, but
 the number of the index (or index + 1). So if the size is the third argument,
 index 2, the value should be 3.
 {{< /caution >}}
 
+These flags can be combined, see the example below.
+
 ```yaml
 - call: "sys_write"
   syscall: true

pkg/k8s/apis/cilium.io/client/crds/v1alpha1/cilium.io_tracingpolicies.yaml

@@ -51,13 +51,22 @@ spec:
                             type: integer
                           maxData:
                             default: false
-                            description: Read maximum possible data. This field is
-                              used only for char_buf type.
+                            description: Read maximum possible data (currently 327360).
+                              This field is only used for char_buff data. When this
+                              value is false (default), the bpf program will fetch
+                              at most 4096 bytes. In later kernels (>=5.4) tetragon
+                              supports fetching up to 327360 bytes if this flag is
+                              turned on
                             type: boolean
                           returnCopy:
                             default: false
                             description: This field is used only for char_buf and
-                              char_iovec types.
+                              char_iovec types. It indicates that this argument should
+                              be read later (when the kretprobe for the symbol is
+                              triggered) because it might not be populated when the
+                              kprobe is triggered at the entrance of the function.
+                              For example, a buffer supplied to read(2) won't have
+                              content until kretprobe is triggered.
                             type: boolean
                           sizeArgIndex:
                             description: Specifies the position of the corresponding
@@ -114,13 +123,21 @@ spec:
                           type: integer
                         maxData:
                           default: false
-                          description: Read maximum possible data. This field is used
-                            only for char_buf type.
+                          description: Read maximum possible data (currently 327360).
+                            This field is only used for char_buff data. When this
+                            value is false (default), the bpf program will fetch at
+                            most 4096 bytes. In later kernels (>=5.4) tetragon supports
+                            fetching up to 327360 bytes if this flag is turned on
                           type: boolean
                         returnCopy:
                           default: false
                           description: This field is used only for char_buf and char_iovec
-                            types.
+                            types. It indicates that this argument should be read
+                            later (when the kretprobe for the symbol is triggered)
+                            because it might not be populated when the kprobe is triggered
+                            at the entrance of the function. For example, a buffer
+                            supplied to read(2) won't have content until kretprobe
+                            is triggered.
                           type: boolean
                         sizeArgIndex:
                           description: Specifies the position of the corresponding
@@ -530,13 +547,22 @@ spec:
                             type: integer
                           maxData:
                             default: false
-                            description: Read maximum possible data. This field is
-                              used only for char_buf type.
+                            description: Read maximum possible data (currently 327360).
+                              This field is only used for char_buff data. When this
+                              value is false (default), the bpf program will fetch
+                              at most 4096 bytes. In later kernels (>=5.4) tetragon
+                              supports fetching up to 327360 bytes if this flag is
+                              turned on
                             type: boolean
                           returnCopy:
                             default: false
                             description: This field is used only for char_buf and
-                              char_iovec types.
+                              char_iovec types. It indicates that this argument should
+                              be read later (when the kretprobe for the symbol is
+                              triggered) because it might not be populated when the
+                              kprobe is triggered at the entrance of the function.
+                              For example, a buffer supplied to read(2) won't have
+                              content until kretprobe is triggered.
                             type: boolean
                           sizeArgIndex:
                             description: Specifies the position of the corresponding

pkg/k8s/apis/cilium.io/client/crds/v1alpha1/cilium.io_tracingpoliciesnamespaced.yaml

@@ -51,13 +51,22 @@ spec:
                             type: integer
                           maxData:
                             default: false
-                            description: Read maximum possible data. This field is
-                              used only for char_buf type.
+                            description: Read maximum possible data (currently 327360).
+                              This field is only used for char_buff data. When this
+                              value is false (default), the bpf program will fetch
+                              at most 4096 bytes. In later kernels (>=5.4) tetragon
+                              supports fetching up to 327360 bytes if this flag is
+                              turned on
                             type: boolean
                           returnCopy:
                             default: false
                             description: This field is used only for char_buf and
-                              char_iovec types.
+                              char_iovec types. It indicates that this argument should
+                              be read later (when the kretprobe for the symbol is
+                              triggered) because it might not be populated when the
+                              kprobe is triggered at the entrance of the function.
+                              For example, a buffer supplied to read(2) won't have
+                              content until kretprobe is triggered.
                             type: boolean
                           sizeArgIndex:
                             description: Specifies the position of the corresponding
@@ -114,13 +123,21 @@ spec:
                           type: integer
                         maxData:
                           default: false
-                          description: Read maximum possible data. This field is used
-                            only for char_buf type.
+                          description: Read maximum possible data (currently 327360).
+                            This field is only used for char_buff data. When this
+                            value is false (default), the bpf program will fetch at
+                            most 4096 bytes. In later kernels (>=5.4) tetragon supports
+                            fetching up to 327360 bytes if this flag is turned on
                           type: boolean
                         returnCopy:
                           default: false
                           description: This field is used only for char_buf and char_iovec
-                            types.
+                            types. It indicates that this argument should be read
+                            later (when the kretprobe for the symbol is triggered)
+                            because it might not be populated when the kprobe is triggered
+                            at the entrance of the function. For example, a buffer
+                            supplied to read(2) won't have content until kretprobe
+                            is triggered.
                           type: boolean
                         sizeArgIndex:
                           description: Specifies the position of the corresponding
@@ -530,13 +547,22 @@ spec:
                             type: integer
                           maxData:
                             default: false
-                            description: Read maximum possible data. This field is
-                              used only for char_buf type.
+                            description: Read maximum possible data (currently 327360).
+                              This field is only used for char_buff data. When this
+                              value is false (default), the bpf program will fetch
+                              at most 4096 bytes. In later kernels (>=5.4) tetragon
+                              supports fetching up to 327360 bytes if this flag is
+                              turned on
                             type: boolean
                           returnCopy:
                             default: false
                             description: This field is used only for char_buf and
-                              char_iovec types.
+                              char_iovec types. It indicates that this argument should
+                              be read later (when the kretprobe for the symbol is
+                              triggered) because it might not be populated when the
+                              kprobe is triggered at the entrance of the function.
+                              For example, a buffer supplied to read(2) won't have
+                              content until kretprobe is triggered.
                             type: boolean
                           sizeArgIndex:
                             description: Specifies the position of the corresponding

pkg/k8s/apis/cilium.io/v1alpha1/types.go

@@ -139,11 +139,18 @@ type KProbeArg struct {
 	SizeArgIndex uint32 `json:"sizeArgIndex"`
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:default=false
-	// This field is used only for char_buf and char_iovec types.
+    // This field is used only for char_buf and char_iovec types. It indicates
+    // that this argument should be read later (when the kretprobe for the
+    // symbol is triggered) because it might not be populated when the kprobe
+    // is triggered at the entrance of the function. For example, a buffer
+    // supplied to read(2) won't have content until kretprobe is triggered.
 	ReturnCopy bool `json:"returnCopy"`
 	// +kubebuilder:validation:Optional
 	// +kubebuilder:default=false
-	// Read maximum possible data. This field is used only for char_buf type.
+    // Read maximum possible data (currently 327360). This field is only used
+    // for char_buff data. When this value is false (default), the bpf program
+    // will fetch at most 4096 bytes. In later kernels (>=5.4) tetragon
+    // supports fetching up to 327360 bytes if this flag is turned on
 	MaxData bool `json:"maxData"`
 }