Improved README and configuration documentation (#17)

Author: Mario Macias

README.md

@@ -1,19 +1,42 @@
 # 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
 
 ```
 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
 

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.

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"`
 }