chore(docs): updates for new falcoctl driver tool. #1240

FedeDP · 2024-01-16T15:25:28Z

What type of PR is this?

/kind cleanup

Any specific area of the project related to this PR?

/area documentation

What this PR does / why we need it:

Updated falco-driver-loader related documentation to use new falcoctl driver tool that will be shipped by Falco 0.37.
Moreover, it updates the way to select a given driver in Falco, given the new engine config file options.

Finally, it uses a more coherent legacy eBPF naming in place of traditional or classic, everywhere.

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

FedeDP · 2024-01-16T15:25:34Z

/hold

FedeDP · 2024-01-16T15:29:21Z

Then, we will need a subsequent PR to also update ways to run Falco with different drivers, now that Falco deprecated old FALCO_BPF_PROBE and --modern-bpf, and make use of new engine.kind configuration key.

I can do that in this PR since they are a bit tied together.

FedeDP · 2024-01-16T15:55:48Z

Ok, ported FALCO_BPF_PROBE and --modern-bpf documentation to new engine.kind Falco config option.
Moreover, dropped userspace instrumentation since it was already deprecated and its support has been removed from Falco in the 0.37 release cycle.

content/en/docs/event-sources/kernel/_index.md

Signed-off-by: Federico Di Pierro <[email protected]>

…g it with new `engine.kind` Falco config key. Signed-off-by: Federico Di Pierro <[email protected]>

…and has been dropped. Signed-off-by: Federico Di Pierro <[email protected]>

FedeDP · 2024-01-29T09:04:33Z

Rebased on top of master.

…ction. Signed-off-by: Federico Di Pierro <[email protected]> Co-authored-by: Luca Guerra <[email protected]>

incertum · 2024-01-30T03:14:46Z

content/en/docs/event-sources/kernel/_index.md

 - Modern eBPF probe
+- Classic eBPF probe


Classic or didn't we agree on Legacy? My preference would be Legacy as I believe most other docs call it that way.

incertum · 2024-01-30T03:16:09Z

content/en/docs/event-sources/kernel/_index.md

-
- 	As you can notice, when your `kernel.perf_event_paranoid` is `>2` the capability `CAP_PERFMON` won't suffice, you would still need `CAP_SYS_ADMIN`.
- 	So before disabling `CAP_SYS_ADMIN` check your `perf_event_paranoid` value with `sysctl kernel.perf_event_paranoid` and make sure their values are compatible with your distribution enforcement.
-
 ## Modern eBPF probe

 The {{< glossary_tooltip text="modern probe" term_id="modern-ebpf-probe" >}} is an alternative driver for Falco. The main advantage it brings to the table is that it is embedded into Falco, which means that you don't have to download or build anything, if your kernel is recent enough Falco will automatically inject it!


modern probe? stay consistent with modern_ebpf?

incertum · 2024-01-30T03:18:32Z

content/en/docs/event-sources/kernel/_index.md

@@ -97,13 +54,16 @@ sudo bpftool feature probe kernel | grep -q "program_type tracing is available"

 ### How to run it

-The modern eBPF probe supports all the installation methods of other drivers:
+To enable the modern eBPF support in Falco, just set the `engine.kind` configuration key to `modern_ebpf`. Nothing else will be needed since no external artifact is required for it to work.


Perhaps say something similar to https://github.com/falcosecurity/falco-website/pull/1246/files#diff-c3777e5fb1d24e6ce0aae8a99b12234f648c9ef9ed17e4b858fce246deffad5eR40

incertum · 2024-01-30T03:19:29Z

content/en/docs/event-sources/kernel/_index.md


-The Falco community, in 0.24.0 promoted the userspace instrumentation feature to **[official support](https://github.com/falcosecurity/evolution#official-support)** to be included in Falco.
+To enable the eBPF support in Falco set the `engine.kind` configuration key to `ebpf` and eventually customize `engine.ebpf.probe`  to the path where the eBPF probe resides; the default path is the location used by `falcoctl driver` tool to install the eBPF probe.


Tell what the default path is here as well.

incertum · 2024-01-30T03:20:39Z

content/en/docs/install-operate/download.md

@@ -36,7 +36,7 @@ If you use Falco for non-syscall events, such as some plugins, only download the
 When using Falco for syscall monitoring, the Falco binary relies on having Falco's kernel driver available, which can fit into two paradigms based on its type:

 1. Falco with modern BPF driver: Download the Falco binary artifact; the driver is already included in the binary, made possible by the CO-RE "Compile Once - Run Everywhere" feature, so no further action is needed.
-2. Falco with kernel module or traditional BPF driver: Also, download the Falco binary artifact, and additionally, download the kernel artifact corresponding to your kernel release (`uname -r`) for either `.ko` (kernel module) or `.o` (BPF driver) from the [driver](https://download.falco.org/?prefix=driver/) store. Navigate to the driver versions' directory that is compatible with the Falco binary (check with `falco --version`). To make this easier, Falco has a `falco-driver-loader` component that automates the driver download or tries to build it. The [Install](/docs/install-operate/installation/) guide will explain this more and the text blob below also has more information.
+2. Falco with kernel module or traditional BPF driver: Also, download the Falco binary artifact, and additionally, download the kernel artifact corresponding to your kernel release (`uname -r`) for either `.ko` (kernel module) or `.o` (BPF driver) from the [driver](https://download.falco.org/?prefix=driver/) store. Navigate to the driver versions' directory that is compatible with the Falco binary (check with `falco --version`). To make this easier, Falco has a `falcoctl driver` component that automates the driver download or tries to build it. The [Install](/docs/install-operate/installation/) guide will explain this more and the text blob below also has more information.


And we call it traditional BPF driver -> change to consistent legacy eBPF driver

Also change all old BPF driver references to eBPF ...

Great catches!

incertum · 2024-01-30T03:24:03Z

content/en/docs/install-operate/upgrade.md

@@ -109,6 +109,6 @@ For the Falco binary we don't provide specific update paths, you just have to re

 ## Special Note on Kernel Drivers and Kernel Upgrades

-When performing kernel upgrades on your host, a reboot is required. Consequently, the Falco binary restarts, and additionally, you must ensure that a new kernel driver corresponding to the updated kernel release (`uname -r`) is available when using the kernel module or traditional BPF driver. By using Falco's `falco-driver-loader`, these processes are automated for you, making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.
+When performing kernel upgrades on your host, a reboot is required. Consequently, the Falco binary restarts, and additionally, you must ensure that a new kernel driver corresponding to the updated kernel release (`uname -r`) is available when using the kernel module or traditional BPF driver. By using Falco's `falcoctl driver` tool, these processes are automated for you, making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.


same old "traditional BPF driver" ref

incertum · 2024-01-30T03:24:59Z

content/en/docs/install-operate/upgrade.md

@@ -109,6 +109,6 @@ For the Falco binary we don't provide specific update paths, you just have to re

 ## Special Note on Kernel Drivers and Kernel Upgrades

-When performing kernel upgrades on your host, a reboot is required. Consequently, the Falco binary restarts, and additionally, you must ensure that a new kernel driver corresponding to the updated kernel release (`uname -r`) is available when using the kernel module or traditional BPF driver. By using Falco's `falco-driver-loader`, these processes are automated for you, making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.
+When performing kernel upgrades on your host, a reboot is required. Consequently, the Falco binary restarts, and additionally, you must ensure that a new kernel driver corresponding to the updated kernel release (`uname -r`) is available when using the kernel module or traditional BPF driver. By using Falco's `falcoctl driver` tool, these processes are automated for you, making it easy to handle kernel upgrades. The Falco Project features a kernel crawler and automated CI, ensuring you can always obtain the necessary pre-built driver artifact, even for the latest kernel releases we support.

 The great news is that modern BPF driver is more resilient to it, because of the CO-RE "Compile Once - Run Everywhere" feature that made it possible to bundle the driver into the Falco binary - it will just continue to work on the upgraded kernel. If possible, use modern BPF!


Actually could we string search for "modern BPF" and "traditional BPF" or "classic BPF" and change everything in one swing?

…ional to legacy for the old bpf probe. Signed-off-by: Federico Di Pierro <[email protected]> Co-authored-by: Melissa Kilby <[email protected]>

FedeDP · 2024-01-30T08:34:42Z

@incertum done everything! Thanks for the huge feedback!

leogr

LGTM

/hold for the 0.37

poiana · 2024-01-30T10:10:48Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: FedeDP, leogr

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/OWNERS~~ [leogr]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

leogr · 2024-01-30T14:33:15Z

/hold cancel

poiana added kind/cleanup dco-signoff: yes area/documentation labels Jan 16, 2024

poiana added the do-not-merge/hold label Jan 16, 2024

poiana requested review from mstemm and vjjmiras January 16, 2024 15:25

poiana added the size/M label Jan 16, 2024

poiana added size/L and removed size/M labels Jan 16, 2024

FedeDP mentioned this pull request Jan 17, 2024

[TRACKING] Breaking changes in Falco 0.37.0 falcosecurity/falco#2763

Closed

6 tasks

LucaGuerra added this to the falco-0.37.0 milestone Jan 18, 2024

FedeDP mentioned this pull request Jan 19, 2024

[WIP] [Falco 0.37.0] cleanup(content)!: remove userspace driver support #1166

Closed

LucaGuerra reviewed Jan 23, 2024

View reviewed changes

content/en/docs/event-sources/kernel/_index.md Outdated Show resolved Hide resolved

FedeDP added 3 commits January 29, 2024 10:04

chore(docs): updates for new falcoctl driver tool.

ab836e6

Signed-off-by: Federico Di Pierro <[email protected]>

cleanup(docs): drop FALCO_BPF_PROBE and --modern-bpf usages, replacin…

507b6fd

…g it with new `engine.kind` Falco config key. Signed-off-by: Federico Di Pierro <[email protected]>

cleanup(docs): dropped userspace instrumentation that was deprecated …

5a95a1c

…and has been dropped. Signed-off-by: Federico Di Pierro <[email protected]>

FedeDP force-pushed the chore/update_falcoctl_driver branch from 9887b1d to d2f3b48 Compare January 29, 2024 09:04

FedeDP force-pushed the chore/update_falcoctl_driver branch 2 times, most recently from ea340dc to b44dc14 Compare January 29, 2024 09:14

chore(content/docs): move modern BPF probe above classic BPF probe se…

0ce23d4

…ction. Signed-off-by: Federico Di Pierro <[email protected]> Co-authored-by: Luca Guerra <[email protected]>

FedeDP force-pushed the chore/update_falcoctl_driver branch from b44dc14 to 0ce23d4 Compare January 29, 2024 09:18

incertum reviewed Jan 30, 2024

View reviewed changes

chore(content/docs): multiple fixes and renamings from classic/tradit…

8d04cbb

…ional to legacy for the old bpf probe. Signed-off-by: Federico Di Pierro <[email protected]> Co-authored-by: Melissa Kilby <[email protected]>

leogr approved these changes Jan 30, 2024

View reviewed changes

poiana assigned leogr Jan 30, 2024

poiana added the lgtm label Jan 30, 2024

poiana added the approved label Jan 30, 2024

poiana removed the do-not-merge/hold label Jan 30, 2024

poiana merged commit 2fe6a74 into falcosecurity:master Jan 30, 2024
4 of 6 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(docs): updates for new falcoctl driver tool. #1240

chore(docs): updates for new falcoctl driver tool. #1240

FedeDP commented Jan 16, 2024 •

edited

Loading

FedeDP commented Jan 16, 2024

FedeDP commented Jan 16, 2024 •

edited

Loading

FedeDP commented Jan 16, 2024

FedeDP commented Jan 29, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

FedeDP Jan 30, 2024

incertum Jan 30, 2024

incertum Jan 30, 2024

FedeDP commented Jan 30, 2024

leogr left a comment

poiana commented Jan 30, 2024

leogr commented Jan 30, 2024


		The Falco community, in 0.24.0 promoted the userspace instrumentation feature to [official support](https://github.com/falcosecurity/evolution#official-support) to be included in Falco.
		To enable the eBPF support in Falco set the `engine.kind` configuration key to `ebpf` and eventually customize `engine.ebpf.probe` to the path where the eBPF probe resides; the default path is the location used by `falcoctl driver` tool to install the eBPF probe.

chore(docs): updates for new falcoctl driver tool. #1240

chore(docs): updates for new falcoctl driver tool. #1240

Conversation

FedeDP commented Jan 16, 2024 • edited Loading

FedeDP commented Jan 16, 2024

FedeDP commented Jan 16, 2024 • edited Loading

FedeDP commented Jan 16, 2024

FedeDP commented Jan 29, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

FedeDP commented Jan 30, 2024

leogr left a comment

Choose a reason for hiding this comment

poiana commented Jan 30, 2024

leogr commented Jan 30, 2024

FedeDP commented Jan 16, 2024 •

edited

Loading

FedeDP commented Jan 16, 2024 •

edited

Loading