add flow filter doc and show some use cases

Signed-off-by: Mohamed Mahmoud <[email protected]>

docs/config.md

@@ -76,6 +76,25 @@ The following environment variables are available to configure the NetObserv eBF
   `PCA_FILTER=tcp,22`.
 * `PCA_SERVER_PORT` (default: 0). Works only when `ENABLE_PCA` is set. Agent opens PCA Server at this port. A collector can connect to it and recieve filtered packets as pcap stream. The filter is set using `PCA_FILTER`.
 * `FLP_CONFIG`: [flowlogs-pipeline](https://github.com/netobserv/flowlogs-pipeline) configuration as YAML or JSON, used when `EXPORT` is `direct-flp`. The ingest stage must be omitted from this configuration, since it is handled internally by the agent. The first stage should follow "preset-ingester". E.g, for a minimal configuration printing on terminal: `{"pipeline":[{"name": "writer","follows": "preset-ingester"}],"parameters":[{"name": "writer","write": {"type": "stdout"}}]}`. Refer to flowlogs-pipeline documentation for more options.
+* `METRICS_ENABLED` (default: `false`). If `true`, the agent will export metrics to the configured `EXPORT` endpoint.
+  * `METRICS_SERVER_ADDRESS` Address of the server where the metrics will be exported.
+  * `METRICS_SERVER_PORT` (default: 9090). Port of the server where the metrics will be exported.
+  * `METRICS_TLS_CERT_PATH` (default: unset). Path to the certificate file for the TLS connection.
+  * `METRICS_TLS_KEY_PATH` (default: unset). Path to the private key file for the TLS connection.
+  * `METRICS_PREFIX` (default: `ebpf-agent`). Prefix for the exported metrics.
+* `ENABLE_FLOW_FILTER` (default: `false`). If `true`, the agent will filter flows based on the configured `FLOW_FILTER`.
+  See [docs](./flow_filtering.md) for more details on this feature.
+  * `FLOW_FILTER_DIRECTION` (default: unset). Direction of the flows to be filtered. Accepted values are `ingress`, `egress`, this is optional configuration.
+  * `FLOW_FILTER_IP_CIDR` (default: unset). IP CIDR to be filtered. Accepted format: `192.168.1.0/24` this field is mandatory.
+  * `FLOW_FILTER_PROTOCOL` (default: unset). Protocol to be filtered. Accepted values are `TCP`, `UDP`, `SCTP`, `ICMP`, `ICMPv6`, this is optional configuration.
+  * `FLOW_FILTER_SOURCE_PORT` (default: unset). Source port to be filtered. Accepted format: `80` this field is optional.
+  * `FLOW_FILTER_DESTINATION_PORT` (default: unset). Destination port to be filtered. Accepted format: `80` this field is optional.
+  * `FLOW_FILTER_SOURCE_PORT_RANGE` (default: unset). Source port range to be filtered. Accepted format: `80-90` this field is optional.
+  * `FLOW_FILTER_DESTINATION_PORT_RANGE` (default: unset). Destination port range to be filtered. Accepted format: `80-90` this field is optional.
+  * `FLOW_FILTER_ICMP_TYPE` (default: unset). ICMP type to be filtered. Accepted format: `8` this field is optional.
+  * `FLOW_FILTER_ICMP_CODE` (default: unset). ICMP code to be filtered. Accepted format: `8` this field is optional.
+  * `FLOW_FILTER_IP` (default: unset). IP address to be filtered. Accepted format: `192.168.1.1` this field is optional.
+  * `FLOW_FILTER_ACTION` (default: unset). Action to be taken when the flow is filtered. Accepted values are `Accept`, `Reject`.
 
 
 ## Development-only variables

docs/flow_filtering.md

@@ -0,0 +1,99 @@
+# eBPF Flow Rule Based Filtering
+
+## Introduction 
+
+Flow rule-base filtering is a method to control the flow of packets cached in eBPF's flows table based on certain configuration
+
+## Flow filter rule configuration
+
+ The Flow filter rule consists of two parts mandatory and optional parameters.
+
+### Mandatory parameters
+
+- `FLOW_FILTER_IP_CIDR` - IP address and CIDR mask for the flow filter rule, supports IPv4 and IPv6 address format.
+  If wanted to match against any IP, user can use `0.0.0.0/0` or `::/0` for IPv4 and IPv6 respectively.
+  CIDR configuration for IP Addresses external to the cluster, for incoming traffic it will represent the source addresses
+  and for outgoing traffic it will represent the destination addresses.
+- `FLOW_FILTER_ACTION` - Action to be taken for the flow filter rule. Possible values are `Accept` and `Reject`.
+  - For the matching rule with `Accept` action this flow will be allowed to be cached in eBPF table, with updated global metric `FlowFilterAcceptCounter`.
+  - For the matching rule with `Reject` action this flow will not be cached in eBPF table, with updated global metric `FlowFilterRejectCounter`.
+  - If the rule is not matched, based on the configured action if its `Accept` the flow will not be cached in eBPF table, 
+   if the action is `Reject` then the flow will be cached in the eBPF table and a global metric `FlowFilterNoMatchCounter` will be updated.
+
+### Optional parameters
+
+- `FLOW_FILTER_DIRECTION` - Direction of the flow filter rule. Possible values are `Ingress` and `Egress`.
+- `FLOW_FILTER_PROTOCOL` - Protocol of the flow filter rule. Possible values are `TCP`, `UDP`, `SCTP`, `ICMP`, `ICMPv6`.
+- `FLOW_FILTER_SOURCE_PORT` - Single Source port of the flow filter rule.
+- `FLOW_FILTER_SOURCE_PORT_RANGE` - Source port range of the flow filter rule. using "80-100" format.
+- `FLOW_FILTER_DESTINATION_PORT` - Single Destination port of the flow filter rule.
+- `FLOW_FILTER_DESTINATION_PORT_RANGE` - Destination port range of the flow filter rule. using "80-100" format.
+- `FLOW_FILTER_ICMP_TYPE` - ICMP type of the flow filter rule.
+- `FLOW_FILTER_ICMP_CODE` - ICMP code of the flow filter rule.
+- `FLOW_FILTER_IP` - Specific IP address of the flow filter rule.
+
+## How does it work
+
+### What does IP CIDR filtering work? 
+
+- When filtering ingress traffic, the source IP address is a crucial parameter used to match filter rules configured with CIDR notation.
+  CIDR notation allows for the efficient representation of IP address ranges by combining the base IP address with a prefix length
+  to denote the network subnet.
+- When filtering egress traffic, the destination IP address is a crucial parameter used to match filter rules configured with CIDR notation.
+  CIDR notation allows for the efficient representation of IP address ranges by combining the base IP address with a prefix length.
+
+### Matching specific endpoints using `FLOW_FILTER_IP`
+
+- `FLOW_FILTER_IP` is internal a cluster internal address for example PODs IP.
+- When filtering ingress traffic, the `FLOW_FILTER_IP` will be used to match against the destination IP address of the packet, 
+  so after matching source IP CIDR now we can pinpoint to a specific endpoint via `FLOW_FILTER_IP` and based on the provisioned action,
+  flow with either be allowed to be cached in eBPF flow table or not.
+- When filtering egress traffic, the `FLOW_FILTER_IP` will be used to match against the source IP address of the packet,
+  so after matching destination IP CIDR now we can pinpoint to a specific endpoint via `FLOW_FILTER_IP` and based on the provisioned action,
+  flow with either be allowed to be cached in eBPF flow table or not.
+
+
+### How to fine tune the flow filter rule configuration?
+
+We have many configuration options available for the flow filter rule configuration, but we can use them in combination to achieve the desired
+flow filter rule configuration. Let's use some examples to understand how to fine tune the flow filter rule configuration.
+
+#### Use-case 1:
+
+Filter k8s service traffic to specific POD IP endpoint.
+For example if we wanted to filter in incoming k8s service traffic coming from source `172.210.150.100` for `SCTP` protocol, 
+on specific dport range 80-100, and targeting specific POD IP endpoint at `10.10.10.10` we can use the following configuration:
+
+```shell
+    FLOW_FILTER_IP_CIDR=172.210.150.1/24
+    FLOW_FILTER_ACTION=Accept
+    FLOW_FILTER_PROTOCOL=SCTP
+    FLOW_FILTER_DIRECTION=Ingress
+    FLOW_FILTER_DESTINATION_PORT_RANGE=80-100
+    FLOW_FILTER_IP=10.10.10.10
+```
+
+#### Use-case 2:
+
+Users wanted to see flows after EgressIP feature is configured with EgressIP `192.168.127.12` for `TCP` protocol with sport `100`
+to any cluster's outside addresses (destinations is unknown or don't care), so they can use the following configuration:
+
+```shell
+    FLOW_FILTER_IP_CIDR=0.0.0.0/0
+    FLOW_FILTER_ACTION=Accept
+    FLOW_FILTER_PROTOCOL=TCP
+    FLOW_FILTER_DIRECTION=Egress
+    FLOW_FILTER_SOURCE_PORT=100
+    FLOW_FILTER_IP=192.168.127.12
+```
+
+#### Use-case 3:
+
+OpenShift ovn kubernetes CNI uses `169.254.169.1-4` as masquerade addresses when handle host service traffic
+I am not interested in capturing any those packets, so I can use the following configuration:
+
+```shell
+    FLOW_FILTER_IP_CIDR=169.254.169.1/24
+    FLOW_FILTER_ACTION=Reject
+    FLOW_FILTER_DIRECTION=Ingress
+```