cleanup(config): re-arrange falco.yaml configs in logical categories

* add an index for logical categories
* move configs around without changing description content,
  solely add a uniform header to each config
* indicate "Stable" or "Experimental" for most configs
  to indicate current stability or maturity

Signed-off-by: Melissa Kilby <melissa.kilby.oss@gmail.com>

falco.yaml

@@ -1,5 +1,5 @@
 #
-# Copyright (C) 2022 The Falco Authors.
+# Copyright (C) 2023 The Falco Authors.
 #
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -15,6 +15,72 @@
 # limitations under the License.
 #
 
+################
+# Config index #
+################
+
+# Here is an index of the configuration categories to help you navigate
+# the Falco configuration file:
+#
+# Falco rules + config files
+#     rules_file
+#     watch_config_files
+# Falco outputs (basic)
+#     time_format_iso_8601
+#     priority
+#     json_output
+#     json_include_output_property
+#     json_include_tags_property
+#     stdout_output
+#     syslog_output
+#     file_output
+#     buffered_outputs
+#     outputs (throttling)
+# Falco internal logging / alerting / metrics (basic)
+#     log_stderr
+#     log_syslog
+#     log_level
+#     libs_logger
+# Falco outputs (advanced)
+#     grpc_output
+#     grpc
+#     http_output
+#     program_output
+#     webserver
+# Falco internal logging / alerting / metrics (advanced)
+#     syscall_event_timeouts
+#     syscall_event_drops
+#     metrics
+#     output_timeout
+# Falco cloud native relevant configs
+#     metadata_download
+#     load_plugins
+#     plugins
+# Falco performance tuning
+#     syscall_buf_size_preset
+#     syscall_drop_failed_exit
+#     base_syscalls
+#     modern_bpf.cpus_for_each_syscall_buffer
+
+################################
+# Falco command-line arguments #
+################################
+
+# To explore the latest command-line arguments supported by Falco for additional
+# configuration, you can run `falco --help` in your terminal. You can also pass
+# configuration options from this config file as command-line arguments by using
+# the `-o` flag followed by the option name and value. In the following example,
+# three config options (`json_output`, `log_level`, and `log_stderr`) are passed as
+# command-line arguments with their corresponding values :
+# `falco -o "json_output=true" -o "log_level=debug" -o "log_stderr=true"`. Please
+# note that command-line arguments take precedence over the options specified in
+# this config file.
+
+
+##############################
+# Falco rules + config files #
+##############################
+
 # File(s) or Directories containing Falco rules, loaded at startup.
 # The name "rules_file" is only for backwards compatibility.
 # If the entry is a file, it will be read directly. If the entry is a directory,
@@ -32,47 +98,27 @@ rules_file:
   - /etc/falco/falco_rules.local.yaml
   - /etc/falco/rules.d
 
-#
-# Plugins that are available for use. These plugins are not loaded by
-# default, as they require explicit configuration to point to
-# cloudtrail log files.
-#
-
-# To learn more about the supported formats for
-# init_config/open_params for the cloudtrail plugin, see the README at
-# https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.
-plugins:
-  - name: k8saudit
-    library_path: libk8saudit.so
-    init_config:
-    #   maxEventSize: 262144
-    #   webhookMaxBatchSize: 12582912
-    #   sslCertificate: /etc/falco/falco.pem
-    open_params: "http://:9765/k8s-audit"
-  - name: cloudtrail
-    library_path: libcloudtrail.so
-    # see docs for init_config and open_params:
-    # https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md
-  - name: json
-    library_path: libjson.so
-
-# Setting this list to empty ensures that the above plugins are *not*
-# loaded and enabled by default. If you want to use the above plugins,
-# set a meaningful init_config/open_params for the cloudtrail plugin
-# and then change this to:
-# load_plugins: [cloudtrail, json]
-load_plugins: []
-
 # Watch config file and rules files for modification.
 # When a file is modified, Falco will propagate new config,
 # by reloading itself.
 watch_config_files: true
 
+
+#########################
+# Falco outputs (basic) #
+#########################
+
 # If true, the times displayed in log messages and output messages
 # will be in ISO 8601. By default, times are displayed in the local
 # time zone, as governed by /etc/localtime.
 time_format_iso_8601: false
 
+# Minimum rule priority level to load and run. All rules having a
+# priority more severe than this level will be loaded/run.  Can be one
+# of "emergency", "alert", "critical", "error", "warning", "notice",
+# "informational", "debug".
+priority: debug
+
 # If "true", print falco alert messages and rules file
 # loading/validation results as json, which allows for easier
 # consumption by downstream programs. Default is "false".
@@ -89,6 +135,53 @@ json_include_output_property: true
 # false, the "tags" field will not be included in the json output at all.
 json_include_tags_property: true
 
+# Where security notifications should go.
+# Multiple outputs can be enabled.
+stdout_output:
+  enabled: true
+
+syslog_output:
+  enabled: true
+
+# If keep_alive is set to true, the file will be opened once and
+# continuously written to, with each output message on its own
+# line. If keep_alive is set to false, the file will be re-opened
+# for each output message.
+#
+# Also, the file will be closed and reopened if falco is signaled with
+# SIGUSR1.
+file_output:
+  enabled: false
+  keep_alive: false
+  filename: ./events.txt
+
+# Whether or not output to any of the output channels below is
+# buffered. Defaults to false
+buffered_outputs: false
+
+# A throttling mechanism implemented as a token bucket limits the
+# rate of Falco notifications. One rate limiter is assigned to each event
+# source, so that alerts coming from one can't influence the throttling
+# mechanism of the others. This is controlled by the following options:
+#  - rate: the number of tokens (i.e. right to send a notification)
+#    gained per second. When 0, the throttling mechanism is disabled.
+#    Defaults to 0.
+#  - max_burst: the maximum number of tokens outstanding. Defaults to 1000.
+#
+# With these defaults, the throttling mechanism is disabled.
+# For example, by setting rate to 1 Falco could send up to 1000 notifications
+# after an initial quiet period, and then up to 1 notification per second
+# afterward. It would gain the full burst back after 1000 seconds of
+# no activity.
+outputs:
+  rate: 0
+  max_burst: 1000
+
+
+#######################################################
+# Falco internal logging / alerting / metrics (basic) #
+#######################################################
+
 # Send information logs to stderr and/or syslog Note these are *not* security
 # notification logs! These are just Falco lifecycle (and possibly error) logs.
 log_stderr: true
@@ -111,16 +204,140 @@ libs_logger:
   # "info", "debug", "trace".
   severity: debug
 
-# Minimum rule priority level to load and run. All rules having a
-# priority more severe than this level will be loaded/run.  Can be one
-# of "emergency", "alert", "critical", "error", "warning", "notice",
-# "informational", "debug".
-priority: debug
 
-# Whether or not output to any of the output channels below is
+############################
-# buffered. Defaults to false
+# Falco outputs (advanced) #
-buffered_outputs: false
+############################
 
+# [Stable] `grpc_output` and `grpc`
+#
+# gRPC output service.
+# By default it is off.
+# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
+# Make sure to have a consumer for them or leave this disabled.
+grpc_output:
+  enabled: false
+
+# Falco supports running a gRPC server with two main binding types
+# 1. Over the network with mandatory mutual TLS authentication (mTLS)
+# 2. Over a local unix socket with no authentication
+# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
+# please comment/uncomment and change accordingly the options below to configure it.
+# Important note: if Falco has any troubles creating the gRPC server
+# this information will be logged, however the main Falco daemon will not be stopped.
+# gRPC server over network with (mandatory) mutual TLS configuration.
+# This gRPC server is secure by default so you need to generate certificates and update their paths here.
+# By default the gRPC server is off.
+# You can configure the address to bind and expose it.
+# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
+# grpc:
+#   enabled: true
+#   bind_address: "0.0.0.0:5060"
+#   # when threadiness is 0, Falco sets it by automatically figuring out the number of online cores
+#   threadiness: 0
+#   private_key: "/etc/falco/certs/server.key"
+#   cert_chain: "/etc/falco/certs/server.crt"
+#   root_certs: "/etc/falco/certs/ca.crt"
+
+# gRPC server using an unix socket
+grpc:
+  enabled: false
+  bind_address: "unix:///run/falco/falco.sock"
+  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
+  threadiness: 0
+
+# [Stable] `http_output`
+#
+http_output:
+  enabled: false
+  url: http://some.url
+  user_agent: "falcosecurity/falco"
+  # Tell Falco to not verify the remote server.
+  insecure: false
+  # Path to the CA certificate that can verify the remote server.
+  ca_cert: ""
+  # Path to a specific file that will be used as the CA certificate store.
+  ca_bundle: ""
+  # Path to a folder that will be used as the CA certificate store. CA certificate need to be
+  # stored as indivitual PEM files in this directory.
+  ca_path: "/etc/ssl/certs"
+
+# [Stable] `program_output`
+#
+# Possible additional things you might want to do with program output:
+#   - send to a slack webhook:
+#         program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
+#   - logging (alternate method than syslog):
+#         program: logger -t falco-test
+#   - send over a network connection:
+#         program: nc host.example.com 80
+# If keep_alive is set to true, the program will be started once and
+# continuously written to, with each output message on its own
+# line. If keep_alive is set to false, the program will be re-spawned
+# for each output message.
+#
+# Also, the program will be closed and reopened if falco is signaled with
+# SIGUSR1.
+program_output:
+  enabled: false
+  keep_alive: false
+  program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
+
+# [Stable] `webserver`
+#
+# Falco supports an embedded webserver and exposes the following endpoints:
+# - /healthz: health endpoint useful for checking if Falco is up and running
+#   (the endpoint name is configurable).
+# - /versions: responds with a JSON object containing version numbers of the
+#   internal Falco components (similar output as `falco --version -o json_output=true`).
+#
+# # NOTE: the /versions endpoint is useful to other services (such as falcoctl)
+# to retrieve info about a running Falco instance. Make sure the webserver is
+# enabled if you're using falcoctl either locally or with Kubernetes.
+#
+# The following options control the behavior of that webserver (enabled by default).
+#
+# The ssl_certificate is a combination SSL Certificate and corresponding
+# key contained in a single file. You can generate a key/cert as follows:
+#
+# $ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
+# $ cat certificate.pem key.pem > falco.pem
+# $ sudo cp falco.pem /etc/falco/falco.pem
+webserver:
+  enabled: true
+  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
+  threadiness: 0
+  listen_port: 8765
+  k8s_healthz_endpoint: /healthz
+  ssl_enabled: false
+  ssl_certificate: /etc/falco/falco.pem
+
+
+##########################################################
+# Falco internal logging / alerting / metrics (advanced) #
+##########################################################
+
+# [Stable] `syscall_event_timeouts`
+#
+# Falco uses a shared buffer between the kernel and userspace to receive
+# the events (eg., system call information) in userspace.
+#
+# Anyways, the underlying libraries can also timeout for various reasons.
+# For example, there could have been issues while reading an event.
+# Or the particular event needs to be skipped.
+# Normally, it's very unlikely that Falco does not receive events consecutively.
+#
+# Falco is able to detect such uncommon situation.
+#
+# Here you can configure the maximum number of consecutive timeouts without an event
+# after which you want Falco to alert.
+# By default this value is set to 1000 consecutive timeouts without an event at all.
+# How this value maps to a time interval depends on the CPU frequency.
+syscall_event_timeouts:
+  max_consecutives: 1000
+
+# [Stable] `syscall_event_drops`
+#
 # Falco uses a shared buffer between the kernel and userspace to pass
 # system call information. When Falco detects that this buffer is
 # full and system calls have been dropped, it can take one or more of
@@ -142,7 +359,6 @@ buffered_outputs: false
 #
 # For debugging/testing it is possible to simulate the drops using
 # the `simulate_drops: true`. In this case the threshold does not apply.
-
 syscall_event_drops:
   threshold: .1
   actions:
@@ -152,31 +368,184 @@ syscall_event_drops:
   max_burst: 1
   simulate_drops: false
 
-# Falco uses a shared buffer between the kernel and userspace to receive
+# [Experimental] `metrics`
-# the events (eg., system call information) in userspace.
 #
-# Anyways, the underlying libraries can also timeout for various reasons.
+# periodic metric snapshots (including stats and resource utilization)
-# For example, there could have been issues while reading an event.
+# captured at regular intervals
-# Or the particular event needs to be skipped.
-# Normally, it's very unlikely that Falco does not receive events consecutively.
 #
-# Falco is able to detect such uncommon situation.
+# --- [Description]
 #
-# Here you can configure the maximum number of consecutive timeouts without an event
+# Consider these key points about the `metrics` feature in Falco:
-# after which you want Falco to alert.
+#
-# By default this value is set to 1000 consecutive timeouts without an event at all.
+# - It introduces a redesigned stats/metrics system.
-# How this value maps to a time interval depends on the CPU frequency.
+# - Native support for resource utilization metrics and specialized performance metrics.
+# - Metrics are emitted as monotonic counters at predefined intervals (snapshots).
+# - All metrics are consolidated into a single log message, adhering to the established
+#   rules schema and naming conventions.
+# - Additional info fields complement the metrics and facilitate customized
+#   statistical analyses and correlations.
+# - The metrics framework is designed for easy future extension.
+#
+# The `metrics` feature follows a specific schema and field naming convention. All metrics
+# are collected as subfields under the `output_fields` key, similar to regular Falco rules.
+# Each metric field name adheres to the grammar used in Falco rules.
+# There are two new field classes introduced: `falco.` and `scap.`.
+# The `falco.` class represents userspace counters, statistics, resource utilization,
+# or useful information fields.
+# The `scap.` class represents counters and statistics mostly obtained from Falco's
+# kernel instrumentation before events are sent to userspace, but can include scap
+# userspace stats as well.
+#
+# It's important to note that the output fields and their names can be subject to change
+# until the metrics feature reaches a stable release.
+#
+# To customize the hostname in Falco, you can set the environment variable `FALCO_HOSTNAME`
+# to your desired hostname. This is particularly useful in Kubernetes deployments
+# where the hostname can be set to the pod name.
+#
+# --- [Usage]
+#
+# `enabled`:
+# Disabled by default.
+#
+# `interval`:
+# The stats interval in Falco follows the time duration definitions used by Prometheus.
+# https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations
+#
+# Time durations are specified as a number, followed immediately by one of the following units:
+# ms - milliseconds
+# s - seconds
+# m - minutes
+# h - hours
+# d - days - assuming a day has always 24h
+# w - weeks - assuming a week has always 7d
+# y - years - assuming a year has always 365d
+#
+# Example of a valid time duration: 1h30m20s10ms
+#
+# A minimum interval of 100ms is enforced for metric collection. However, for production environments,
+# we recommend selecting one of the following intervals for optimal monitoring:
+# 15m
+# 30m
+# 1h
+# 4h
+# 6h
+#
+# `output_rule`:
+# To enable seamless metrics and performance monitoring, we recommend emitting metrics as the rule
+# "Falco internal: metrics snapshot." This option is particularly useful when Falco logs are preserved
+# in a data lake.
+# Please note that to use this option, the `log_level` must be set to `info` at a minimum.
+#
+# `output_file`:
+# Append stats to a `jsonl` file. Use with caution in production as Falco does not automatically rotate the file.
+#
+# `resource_utilization_enabled`:
+# Emit CPU and memory usage metrics. CPU usage is reported as a percentage of one CPU and
+# can be normalized to the total number of CPUs to determine overall usage.
+# Memory metrics are provided in raw units (`kb` for `RSS`, `PSS` and `VSZ` or
+# `bytes` for `container_memory_used`) and can be uniformly converted
+# to megabytes (MB) using the `convert_memory_to_mb` functionality.
+# In environments such as Kubernetes, it is crucial to track Falco's container memory usage.
+# To customize the path of the memory metric file, you can create an environment variable
+# named `FALCO_CGROUP_MEM_PATH` and set it to the desired file path. By default, Falco uses
+# the file `/sys/fs/cgroup/memory/memory.usage_in_bytes` to monitor container memory usage,
+# which aligns with Kubernetes' `container_memory_working_set_bytes` metric.
+#
+# `kernel_event_counters_enabled`:
+# Emit kernel side event and drop counters, as an alternative to `syscall_event_drops`,
+# but with some differences. These counters reflect monotonic values since Falco's start
+# and are exported at a constant stats interval.
+#
+# `libbpf_stats_enabled`:
+# Exposes statistics similar to `bpftool prog show`, providing information such as the number
+# of invocations of each BPF program attached by Falco and the time spent in each program
+# measured in nanoseconds.
+# To enable this feature, the kernel must be >= 5.1, and the kernel configuration `/proc/sys/kernel/bpf_stats_enabled`
+# must be set. This option, or an equivalent statistics feature, is not available for non `*bpf*` drivers.
+# Additionally, please be aware that the current implementation of `libbpf` does not
+# support granularity of statistics at the bpf tail call level.
+#
+# todo: prometheus export option
+# todo: syscall_counters_enabled option
+metrics:
+  enabled: false
+  interval: 1h
+  output_rule: true
+  # output_file: /tmp/falco_stats.jsonl
+  resource_utilization_enabled: true
+  kernel_event_counters_enabled: true
+  libbpf_stats_enabled: true
+  convert_memory_to_mb: true
 
-syscall_event_timeouts:
+# [Stable] `output_timeout`
-  max_consecutives: 1000
+#
+# Falco continuously monitors outputs performance. When an output channel does not allow
+# to deliver an alert within a given deadline, an error is reported indicating
+# which output is blocking notifications.
+# The timeout error will be reported to the log according to the above log_* settings.
+# Note that the notification will not be discarded from the output queue; thus,
+# output channels may indefinitely remain blocked.
+# An output timeout error indeed indicate a misconfiguration issue or I/O problems
+# that cannot be recovered by Falco and should be fixed by the user.
+#
+# The "output_timeout" value specifies the duration in milliseconds to wait before
+# considering the deadline exceed.
+#
+# With a 2000ms default, the notification consumer can block the Falco output
+# for up to 2 seconds without reaching the timeout.
+output_timeout: 2000
 
-# Enabling this option allows Falco to drop failed syscalls exit events
-# in the kernel driver before the event is pushed onto the ring buffer.
-# This can enable some small optimization both in CPU usage and ring buffer usage,
-# possibly leading to lower number of event losses.
-# Be careful: enabling it also means losing a bit of visibility on the system.
-syscall_drop_failed_exit: false
 
+#######################################
+# Falco cloud native relevant configs #
+#######################################
+
+# [Stable] `metadata_download`
+#
+# Container orchestrator metadata fetching params
+metadata_download:
+  max_mb: 100
+  chunk_wait_us: 1000
+  watch_freq_sec: 1
+
+# [Experimental] `load_plugins` and `plugins`
+#
+# Setting this list to empty ensures that the above plugins are *not*
+# loaded and enabled by default. If you want to use the above plugins,
+# set a meaningful init_config/open_params for the cloudtrail plugin
+# and then change this to:
+# load_plugins: [cloudtrail, json]
+load_plugins: []
+
+# Plugins that are available for use. These plugins are not loaded by
+# default, as they require explicit configuration to point to
+# cloudtrail log files.
+# To learn more about the supported formats for
+# init_config/open_params for the cloudtrail plugin, see the README at
+# https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md.
+plugins:
+  - name: k8saudit
+    library_path: libk8saudit.so
+    init_config:
+    #   maxEventSize: 262144
+    #   webhookMaxBatchSize: 12582912
+    #   sslCertificate: /etc/falco/falco.pem
+    open_params: "http://:9765/k8s-audit"
+  - name: cloudtrail
+    library_path: libcloudtrail.so
+    # see docs for init_config and open_params:
+    # https://github.com/falcosecurity/plugins/blob/master/plugins/cloudtrail/README.md
+  - name: json
+    library_path: libjson.so
+
+
+############################
+# Falco performance tuning #
+############################
+
+# [Stable] `syscall_buf_size_preset`
+#
 # --- [Description]
 #
 # This is an index that controls the dimension of the syscall buffers.
@@ -232,234 +601,17 @@ syscall_drop_failed_exit: false
 
 syscall_buf_size_preset: 4
 
-############## Modern BPF probe specific ##############
+# [Experimental] `syscall_drop_failed_exit`
-# Please note: these configs regard only the modern BPF probe.
 #
-# `cpus_for_each_syscall_buffer`
+# Enabling this option allows Falco to drop failed syscalls exit events
-#
+# in the kernel driver before the event is pushed onto the ring buffer.
-# --- [Description]
+# This can enable some small optimization both in CPU usage and ring buffer usage,
-#
+# possibly leading to lower number of event losses.
-# This is an index that controls how many CPUs you want to assign to a single
+# Be careful: enabling it also means losing a bit of visibility on the system.
-# syscall buffer (ring buffer). By default, every syscall buffer is associated to
-# 2 CPUs, so the mapping is 1:2. The modern BPF probe allows you to choose different
-# mappings, for example, 1:1 would mean a syscall buffer for each CPU.
-#
-# --- [Usage]
-#
-# You can choose between different indexes: from `0` to `MAX_NUMBER_ONLINE_CPUs`.
-# `0` is a special value and it means a single syscall buffer shared between all
-# your online CPUs. `0` has the same effect as `MAX_NUMBER_ONLINE_CPUs`, the rationale
-# is that `0` allows you to create a single buffer without knowing the number of online
-# CPUs on your system.
-# Let's consider an example to better understand it:
-#
-# Consider a system with 7 online CPUs:
-#
-#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-#
-# - `1` means a syscall buffer for each CPU so 7 buffers
-#
-#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-#                   |     |  |        |  |  |  |
-#       BUFFERs     0     1  2        3  4  5  6
-#
-# - `2` (Default value) means a syscall buffer for each CPU pair, so 4 buffers
-#
-#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-#                   |     |  |        |  |  |  |
-#       BUFFERs     0     0  1        1  2  2  3
-#
-# Please note that we need 4 buffers, 3 buffers are associated with CPU pairs, the last
-# one is mapped with just 1 CPU since we have an odd number of CPUs.
-#
-# - `0` or `MAX_NUMBER_ONLINE_CPUs` mean a syscall buffer shared between all CPUs, so 1 buffer
-#
-#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-#                   |     |  |        |  |  |  |
-#       BUFFERs     0     0  0        0  0  0  0
-#
-# Moreover you can combine this param with `syscall_buf_size_preset`
-# index, for example, you could create a huge single syscall buffer
-# shared between all your online CPUs of 512 MB (so `syscall_buf_size_preset=10`).
-#
-# --- [Suggestions]
-#
-# We chose index `2` (so one syscall buffer for each CPU pair) as default because the modern bpf probe
-# follows a different memory allocation strategy with respect to the other 2 drivers (bpf and kernel module).
-# By the way, you are free to find the preferred configuration for your system.
-# Considering a fixed `syscall_buf_size_preset` and so a fixed buffer dimension:
-# - a lower number of buffers can speed up your system (lower memory footprint)
-# - a too lower number of buffers could increase contention in the kernel causing an
-#   overall slowdown of the system.
-# If you don't have huge events throughputs and you are not experimenting with tons of drops
-# you can try to reduce the number of buffers to have a lower memory footprint
 
-modern_bpf:
+syscall_drop_failed_exit: false
-  cpus_for_each_syscall_buffer: 2
-############## Modern BPF probe specific ##############
 
-# Falco continuously monitors outputs performance. When an output channel does not allow
+# [Experimental] `base_syscalls`, use with caution, read carefully
-# to deliver an alert within a given deadline, an error is reported indicating
-# which output is blocking notifications.
-# The timeout error will be reported to the log according to the above log_* settings.
-# Note that the notification will not be discarded from the output queue; thus,
-# output channels may indefinitely remain blocked.
-# An output timeout error indeed indicate a misconfiguration issue or I/O problems
-# that cannot be recovered by Falco and should be fixed by the user.
-#
-# The "output_timeout" value specifies the duration in milliseconds to wait before
-# considering the deadline exceed.
-#
-# With a 2000ms default, the notification consumer can block the Falco output
-# for up to 2 seconds without reaching the timeout.
-
-output_timeout: 2000
-
-# A throttling mechanism implemented as a token bucket limits the
-# rate of Falco notifications. One rate limiter is assigned to each event
-# source, so that alerts coming from one can't influence the throttling
-# mechanism of the others. This is controlled by the following options:
-#  - rate: the number of tokens (i.e. right to send a notification)
-#    gained per second. When 0, the throttling mechanism is disabled.
-#    Defaults to 0.
-#  - max_burst: the maximum number of tokens outstanding. Defaults to 1000.
-#
-# With these defaults, the throttling mechanism is disabled.
-# For example, by setting rate to 1 Falco could send up to 1000 notifications
-# after an initial quiet period, and then up to 1 notification per second
-# afterward. It would gain the full burst back after 1000 seconds of
-# no activity.
-
-outputs:
-  rate: 0
-  max_burst: 1000
-
-# Where security notifications should go.
-# Multiple outputs can be enabled.
-
-syslog_output:
-  enabled: true
-
-# If keep_alive is set to true, the file will be opened once and
-# continuously written to, with each output message on its own
-# line. If keep_alive is set to false, the file will be re-opened
-# for each output message.
-#
-# Also, the file will be closed and reopened if falco is signaled with
-# SIGUSR1.
-
-file_output:
-  enabled: false
-  keep_alive: false
-  filename: ./events.txt
-
-stdout_output:
-  enabled: true
-
-# Falco supports an embedded webserver and exposes the following endpoints:
-# - /healthz: health endpoint useful for checking if Falco is up and running
-#   (the endpoint name is configurable).
-# - /versions: responds with a JSON object containing version numbers of the
-#   internal Falco components (similar output as `falco --version -o json_output=true`).
-#
-# # NOTE: the /versions endpoint is useful to other services (such as falcoctl)
-# to retrieve info about a running Falco instance. Make sure the webserver is
-# enabled if you're using falcoctl either locally or with Kubernetes.
-#
-# The following options control the behavior of that webserver (enabled by default).
-#
-# The ssl_certificate is a combination SSL Certificate and corresponding
-# key contained in a single file. You can generate a key/cert as follows:
-#
-# $ openssl req -newkey rsa:2048 -nodes -keyout key.pem -x509 -days 365 -out certificate.pem
-# $ cat certificate.pem key.pem > falco.pem
-# $ sudo cp falco.pem /etc/falco/falco.pem
-webserver:
-  enabled: true
-  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
-  threadiness: 0
-  listen_port: 8765
-  k8s_healthz_endpoint: /healthz
-  ssl_enabled: false
-  ssl_certificate: /etc/falco/falco.pem
-
-# Possible additional things you might want to do with program output:
-#   - send to a slack webhook:
-#         program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
-#   - logging (alternate method than syslog):
-#         program: logger -t falco-test
-#   - send over a network connection:
-#         program: nc host.example.com 80
-
-# If keep_alive is set to true, the program will be started once and
-# continuously written to, with each output message on its own
-# line. If keep_alive is set to false, the program will be re-spawned
-# for each output message.
-#
-# Also, the program will be closed and reopened if falco is signaled with
-# SIGUSR1.
-program_output:
-  enabled: false
-  keep_alive: false
-  program: "jq '{text: .output}' | curl -d @- -X POST https://hooks.slack.com/services/XXX"
-
-http_output:
-  enabled: false
-  url: http://some.url
-  user_agent: "falcosecurity/falco"
-  # Tell Falco to not verify the remote server.
-  insecure: false
-  # Path to the CA certificate that can verify the remote server.
-  ca_cert: ""
-  # Path to a specific file that will be used as the CA certificate store.
-  ca_bundle: ""
-  # Path to a folder that will be used as the CA certificate store. CA certificate need to be
-  # stored as indivitual PEM files in this directory.
-  ca_path: "/etc/ssl/certs"
-
-# Falco supports running a gRPC server with two main binding types
-# 1. Over the network with mandatory mutual TLS authentication (mTLS)
-# 2. Over a local unix socket with no authentication
-# By default, the gRPC server is disabled, with no enabled services (see grpc_output)
-# please comment/uncomment and change accordingly the options below to configure it.
-# Important note: if Falco has any troubles creating the gRPC server
-# this information will be logged, however the main Falco daemon will not be stopped.
-# gRPC server over network with (mandatory) mutual TLS configuration.
-# This gRPC server is secure by default so you need to generate certificates and update their paths here.
-# By default the gRPC server is off.
-# You can configure the address to bind and expose it.
-# By modifying the threadiness configuration you can fine-tune the number of threads (and context) it will use.
-# grpc:
-#   enabled: true
-#   bind_address: "0.0.0.0:5060"
-#   # when threadiness is 0, Falco sets it by automatically figuring out the number of online cores
-#   threadiness: 0
-#   private_key: "/etc/falco/certs/server.key"
-#   cert_chain: "/etc/falco/certs/server.crt"
-#   root_certs: "/etc/falco/certs/ca.crt"
-
-# gRPC server using an unix socket
-grpc:
-  enabled: false
-  bind_address: "unix:///run/falco/falco.sock"
-  # when threadiness is 0, Falco automatically guesses it depending on the number of online cores
-  threadiness: 0
-
-# gRPC output service.
-# By default it is off.
-# By enabling this all the output events will be kept in memory until you read them with a gRPC client.
-# Make sure to have a consumer for them or leave this disabled.
-grpc_output:
-  enabled: false
-
-# Container orchestrator metadata fetching params
-metadata_download:
-  max_mb: 100
-  chunk_wait_us: 1000
-  watch_freq_sec: 1
-
-
-# base_syscalls ! [EXPERIMENTAL] Use with caution, read carefully !
 #
 # --- [Description]
 #
@@ -561,116 +713,69 @@ metadata_download:
 # running process opens a file or makes a network connection, consider adding the
 # following to the above recommended syscall sets:
 # ... setresuid, setsid, setuid, setgid, setpgid, setresgid, setsid, capset, chdir, chroot, fchdir ...
-#
+
 base_syscalls:
   custom_set: []
   repair: false
 
-# metrics: [EXPERIMENTAL] periodic metric snapshots
+# [Experimental] `modern_bpf.cpus_for_each_syscall_buffer`, modern_bpf only
-# (including stats and resource utilization) captured at regular intervals
 #
 # --- [Description]
 #
-# Consider these key points about the `metrics` feature in Falco:
+# This is an index that controls how many CPUs you want to assign to a single
-#
+# syscall buffer (ring buffer). By default, every syscall buffer is associated to
-# - It introduces a redesigned stats/metrics system.
+# 2 CPUs, so the mapping is 1:2. The modern BPF probe allows you to choose different
-# - Native support for resource utilization metrics and specialized performance metrics.
+# mappings, for example, 1:1 would mean a syscall buffer for each CPU.
-# - Metrics are emitted as monotonic counters at predefined intervals (snapshots).
-# - All metrics are consolidated into a single log message, adhering to the established
-#   rules schema and naming conventions.
-# - Additional info fields complement the metrics and facilitate customized
-#   statistical analyses and correlations.
-# - The metrics framework is designed for easy future extension.
-#
-# The `metrics` feature follows a specific schema and field naming convention. All metrics
-# are collected as subfields under the `output_fields` key, similar to regular Falco rules.
-# Each metric field name adheres to the grammar used in Falco rules.
-# There are two new field classes introduced: `falco.` and `scap.`.
-# The `falco.` class represents userspace counters, statistics, resource utilization,
-# or useful information fields.
-# The `scap.` class represents counters and statistics mostly obtained from Falco's
-# kernel instrumentation before events are sent to userspace, but can include scap
-# userspace stats as well.
-#
-# It's important to note that the output fields and their names can be subject to change
-# until the metrics feature reaches a stable release.
-#
-# To customize the hostname in Falco, you can set the environment variable `FALCO_HOSTNAME`
-# to your desired hostname. This is particularly useful in Kubernetes deployments
-# where the hostname can be set to the pod name.
 #
 # --- [Usage]
 #
-# `enabled`:
+# You can choose between different indexes: from `0` to `MAX_NUMBER_ONLINE_CPUs`.
-# Disabled by default.
+# `0` is a special value and it means a single syscall buffer shared between all
+# your online CPUs. `0` has the same effect as `MAX_NUMBER_ONLINE_CPUs`, the rationale
+# is that `0` allows you to create a single buffer without knowing the number of online
+# CPUs on your system.
+# Let's consider an example to better understand it:
 #
-# `interval`:
+# Consider a system with 7 online CPUs:
-# The stats interval in Falco follows the time duration definitions used by Prometheus.
-# https://prometheus.io/docs/prometheus/latest/querying/basics/#time-durations
 #
-# Time durations are specified as a number, followed immediately by one of the following units:
+#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-# ms - milliseconds
-# s - seconds
-# m - minutes
-# h - hours
-# d - days - assuming a day has always 24h
-# w - weeks - assuming a week has always 7d
-# y - years - assuming a year has always 365d
 #
-# Example of a valid time duration: 1h30m20s10ms
+# - `1` means a syscall buffer for each CPU so 7 buffers
 #
-# A minimum interval of 100ms is enforced for metric collection. However, for production environments,
+#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-# we recommend selecting one of the following intervals for optimal monitoring:
+#                   |     |  |        |  |  |  |
-# 15m
+#       BUFFERs     0     1  2        3  4  5  6
-# 30m
-# 1h
-# 4h
-# 6h
 #
-# `output_rule`:
+# - `2` (Default value) means a syscall buffer for each CPU pair, so 4 buffers
-# To enable seamless metrics and performance monitoring, we recommend emitting metrics as the rule
-# "Falco internal: metrics snapshot." This option is particularly useful when Falco logs are preserved
-# in a data lake.
-# Please note that to use this option, the `log_level` must be set to `info` at a minimum.
 #
-# `output_file`:
+#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-# Append stats to a `jsonl` file. Use with caution in production as Falco does not automatically rotate the file.
+#                   |     |  |        |  |  |  |
+#       BUFFERs     0     0  1        1  2  2  3
 #
-# `resource_utilization_enabled`:
+# Please note that we need 4 buffers, 3 buffers are associated with CPU pairs, the last
-# Emit CPU and memory usage metrics. CPU usage is reported as a percentage of one CPU and
+# one is mapped with just 1 CPU since we have an odd number of CPUs.
-# can be normalized to the total number of CPUs to determine overall usage.
-# Memory metrics are provided in raw units (`kb` for `RSS`, `PSS` and `VSZ` or
-# `bytes` for `container_memory_used`) and can be uniformly converted
-# to megabytes (MB) using the `convert_memory_to_mb` functionality.
-# In environments such as Kubernetes, it is crucial to track Falco's container memory usage.
-# To customize the path of the memory metric file, you can create an environment variable
-# named `FALCO_CGROUP_MEM_PATH` and set it to the desired file path. By default, Falco uses
-# the file `/sys/fs/cgroup/memory/memory.usage_in_bytes` to monitor container memory usage,
-# which aligns with Kubernetes' `container_memory_working_set_bytes` metric.
 #
-# `kernel_event_counters_enabled`:
+# - `0` or `MAX_NUMBER_ONLINE_CPUs` mean a syscall buffer shared between all CPUs, so 1 buffer
-# Emit kernel side event and drop counters, as an alternative to `syscall_event_drops`,
-# but with some differences. These counters reflect monotonic values since Falco's start
-# and are exported at a constant stats interval.
 #
-# `libbpf_stats_enabled`:
+#          CPUs     0  X  2  3  X  X  6  7  8  9   (X means offline CPU)
-# Exposes statistics similar to `bpftool prog show`, providing information such as the number
+#                   |     |  |        |  |  |  |
-# of invocations of each BPF program attached by Falco and the time spent in each program
+#       BUFFERs     0     0  0        0  0  0  0
-# measured in nanoseconds.
-# To enable this feature, the kernel must be >= 5.1, and the kernel configuration `/proc/sys/kernel/bpf_stats_enabled`
-# must be set. This option, or an equivalent statistics feature, is not available for non `*bpf*` drivers.
-# Additionally, please be aware that the current implementation of `libbpf` does not
-# support granularity of statistics at the bpf tail call level.
 #
-# todo: prometheus export option
+# Moreover you can combine this param with `syscall_buf_size_preset`
-# todo: syscall_counters_enabled option
+# index, for example, you could create a huge single syscall buffer
+# shared between all your online CPUs of 512 MB (so `syscall_buf_size_preset=10`).
+#
+# --- [Suggestions]
+#
+# We chose index `2` (so one syscall buffer for each CPU pair) as default because the modern bpf probe
+# follows a different memory allocation strategy with respect to the other 2 drivers (bpf and kernel module).
+# By the way, you are free to find the preferred configuration for your system.
+# Considering a fixed `syscall_buf_size_preset` and so a fixed buffer dimension:
+# - a lower number of buffers can speed up your system (lower memory footprint)
+# - a too lower number of buffers could increase contention in the kernel causing an
+#   overall slowdown of the system.
+# If you don't have huge events throughputs and you are not experimenting with tons of drops
+# you can try to reduce the number of buffers to have a lower memory footprint
 
-metrics:
+modern_bpf:
-  enabled: false
+  cpus_for_each_syscall_buffer: 2
-  interval: 1h
-  output_rule: true
-  # output_file: /tmp/falco_stats.jsonl
-  resource_utilization_enabled: true
-  kernel_event_counters_enabled: true
-  libbpf_stats_enabled: true
-  convert_memory_to_mb: true