diff --git a/README.md b/README.md index 3c35017714c8c1540cc5a4a144ccbc2d3ca38079..287353449f5df55332ca2b1b6fc438ded5836bee 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Network Observability eBPF Agent -Network Observability eBPF Agent. +The Network Observability eBPF Agent allows collecting and aggregating all the ingress and +egress flows on a Linux host (required a Kernel 4.18+ with eBPF enabled). ## How to compile @@ -8,12 +9,34 @@ Network Observability eBPF Agent. make build ``` +## How to configure + +The eBPF Agent is configured by means of environment variables. Check the +[configuration documentation](./docs/config.md) for more details. + ## How to run +The NetObserv eBPF Agent is designed to run as a DaemonSet in OpenShift/K8s. It is triggered and +configured by our [Network Observability Operator](https://github.com/netobserv/network-observability-operator). + +Anyway you can run it directly as an executable with administrative privileges: + ``` -sudo bin/netobserv-ebpf-agent +export FLOWS_TARGET_HOST=... +export FLOWS_TARGET_PORT=... +sudo -E bin/netobserv-ebpf-agent ``` -(Pod deployment will come soon) + +To deploy it as a Pod, you can check the [deployment example](./examples/performance/deployment.yml). + +## Where is the collector? + +As part of our Network Observability solution, the eBPF Agent is designed to send the traced +flows to our [Flowlogs Pipeline](https://github.com/netobserv/flowlogs-pipeline) component. + +In addition, we provide a simple GRPC+Protobuf library to allow implementing your own collector. +Check the [packet counter code](./examples/performance/server/packet-counter-collector.go) +for an example of a simple collector using our library. ## Development receipts diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000000000000000000000000000000000000..0a2eb64472131c08afbfa4f05b8e2d7c4e6e121d --- /dev/null +++ b/docs/config.md @@ -0,0 +1,26 @@ +# eBPF Agent configuration environment variables + +The following environment variables are available to configure the NetObserv eBFP Agent: + +* `FLOWS_TARGET_HOST` (required). Host name or IP of the target Flow collector. +* `FLOWS_TARGET_PORT` (required). Port of the target flow collector. +* `INTERFACES` (optional). Comma-separated list of the interface names from where flows will be collected. If + empty, the agent will use all the interfaces in the system, excepting the ones listed in + the `EXCLUDE_INTERFACES` variable. + If an entry is enclosed by slashes (e.g. `/br-/`), it will match as regular expression, + otherwise it will be matched as a case-sensitive string. +* `EXCLUDE_INTERFACES` (default: `lo`). Comma-separated list of the interface names that will be + excluded from flow tracing. It takes priority over `INTERFACES` values. + If an entry is enclosed by slashes (e.g. `/br-/`), it will match as regular expression, + otherwise it will be matched as a case-sensitive string. +* `SAMPLING` (default: disabled). Rate at which packets should be sampled and sent to the target + collector. E.g. if set to 10, one out of 10 packets, on average, will be sent to the target + collector. +* `CACHE_MAX_FLOWS` (default: `1000`). Number of flows that can be accumulated in the accounting + cache. If the accounter reaches the max number of flows, it flushes them to the collector. +* `CACHE_ACTIVE_TIMEOUT` (default: `5s`). Duration string that specifies the maximum duration + that flows are kept in the accounting cache before being flushed to the collector. +* `LOG_LEVEL` (default: `info`). From more to less verbose: `trace`, `debug`, `info`, `warn`, + `error`, `fatal`, `panic`. +* `BUFFERS_LENGTH` (default: `50`). Length of the internal communication channels between the different + processing stages. Most probably you won't need to change this value. diff --git a/pkg/agent/config.go b/pkg/agent/config.go index 7bb25c93d5fcaf932bc6197c3de1b6424e2880f3..e3b276d556441a48ce1577444f4eb4fdf7283390 100644 --- a/pkg/agent/config.go +++ b/pkg/agent/config.go @@ -11,7 +11,7 @@ import ( type Config struct { // TargetHost is the host name or IP of the target Flow collector TargetHost string `env:"FLOWS_TARGET_HOST,notEmpty"` - // TargetHost is the port the target Flow collector + // TargetPort is the port the target Flow collector TargetPort int `env:"FLOWS_TARGET_PORT,notEmpty"` // Interfaces contains the interface names from where flows will be collected. If empty, the agent // will fetch all the interfaces in the system, excepting the ones listed in ExcludeInterfaces. @@ -27,15 +27,15 @@ type Config struct { // stages BuffersLength int `env:"BUFFERS_LENGTH" envDefault:"50"` // CacheMaxFlows specifies how many flows can be accumulated in the accounting cache before - // being flushing the cache for its later export + // being flushed for its later export CacheMaxFlows int `env:"CACHE_MAX_FLOWS" envDefault:"1000"` - // CacheActiveTimeout specifies the maximum duration in which a flow is kept in the accounting + // CacheActiveTimeout specifies the maximum duration that flows are kept in the accounting // cache before being flushed for its later export CacheActiveTimeout time.Duration `env:"CACHE_ACTIVE_TIMEOUT" envDefault:"5s"` // Logger level. From more to less verbose: trace, debug, info, warn, error, fatal, panic. LogLevel string `env:"LOG_LEVEL" envDefault:"info"` // Sampling holds the rate at which packets should be sampled and sent to the target collector. - // E.g. if set to 100, one out of 100 packets, on average, will be sent to each target collector. + // E.g. if set to 100, one out of 100 packets, on average, will be sent to the target collector. Sampling uint32 `env:"SAMPLING" envDefault:"0"` }