Daemon Configuration

Explore Tetragon options and configuration mechanisms.

Tetragon default controlling settings are set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. This document lists those controlling settings and how they can be set as a CLI arguments or as configuration options from YAML files.

Options

The following table list all Tetragon daemon available options and is automatically generated using the tetragon binary --generate-docs flag. The same information can also be retrieved using --help.

Flag Usage Default Value
--bpf-dir Set tetragon bpf directory (default 'tetragon') tetragon
--bpf-lib Location of Tetragon libs (btf and bpf files) /var/lib/tetragon/
--btf Location of btf
--cgroup-rate Base sensor events cgroup rate <events,interval> disabled by default ('1000/1s' means rate 1000 events per second
--config-dir Configuration directory that contains a file for each option
--cpuprofile Store CPU profile into provided file
--cri-endpoint CRI endpoint
--data-cache-size Size of the data events cache 1024
--debug Enable debug messages. Equivalent to '--log-level=debug' false
--disable-kprobe-multi Allow to disable kprobe multi interface false
--enable-cgidmap enable pod resolution via cgroup ids false
--enable-cgidmap-debug enable cgidmap debugging info false
--enable-cri enable CRI client for tetragon false
--enable-export-aggregation Enable JSON export aggregation false
--enable-k8s-api Access Kubernetes API to associate Tetragon events with Kubernetes pods false
--enable-msg-handling-latency Enable metrics for message handling latency false
--enable-pid-set-filter Enable pidSet export filters. Not recommended for production use false
--enable-pod-info Enable PodInfo custom resource false
--enable-policy-filter Enable policy filter code (beta) false
--enable-policy-filter-debug Enable policy filter debug messages false
--enable-process-ancestors Include ancestors in process exec events true
--enable-process-cred Enable process_cred events false
--enable-process-ns Enable namespace information in process_exec and process_kprobe events false
--enable-tracing-policy-crd Enable TracingPolicy and TracingPolicyNamespaced custom resources true
--event-cache-retries Number of retries for event cache 15
--event-cache-retry-delay Delay in seconds between event cache retries 2
--event-queue-size Set the size of the internal event queue. 10000
--export-aggregation-buffer-size Aggregator channel buffer size 10000
--export-aggregation-window-size JSON export aggregation time window 15s
--export-allowlist JSON export allowlist
--export-denylist JSON export denylist
--export-file-compress Compress rotated JSON export files false
--export-file-max-backups Number of rotated JSON export files to retain 5
--export-file-max-size-mb Size in MB for rotating JSON export files 10
--export-file-perm Access permissions on JSON export files 600
--export-file-rotation-interval Interval at which to rotate JSON export files in addition to rotating them by size 0s
--export-filename Filename for JSON export. Disabled by default
--export-rate-limit Rate limit (per minute) for event export. Set to -1 to disable -1
--expose-kernel-addresses Expose real kernel addresses in events stack traces false
--expose-stack-addresses Expose real linear addresses in events stack traces false
--field-filters Field filters for event exports
--force-large-progs Force loading large programs, even in kernels with < 5.3 versions false
--force-small-progs Force loading small programs, even in kernels with >= 5.3 versions false
--generate-docs Generate documentation in YAML format to stdout false
--gops-address gops server address (e.g. 'localhost:8118'). Disabled by default
--health-server-address Health server address (e.g. ':6789')(use '' to disabled it) :6789
--health-server-interval Health server interval in seconds 10
--help help for tetragon false
--k8s-kubeconfig-path Absolute path of the kubernetes kubeconfig file
--keep-sensors-on-exit Do not unload sensors on exit false
--kernel Kernel version
--log-format Set log format text
--log-level Set log level info
--memprofile Store MEM profile into provided file
--metrics-label-filter Comma-separated list of enabled metrics labels. Unknown labels will be ignored. namespace,workload,pod,binary
--metrics-server Metrics server address (e.g. ':2112'). Disabled by default
--netns-dir Network namespace dir /var/run/docker/netns/
--pprof-addr
--pprof-address Serves runtime profile data via HTTP (e.g. 'localhost:6060'). Disabled by default
--process-cache-size Size of the process cache 65536
--procfs Location of procfs to consume existing PIDs /proc/
--rb-queue-size Set size of channel between ring buffer and sensor go routines (default 65k, allows K/M/G suffix) 65535
--rb-size Set perf ring buffer size for single cpu (default 65k, allows K/M/G suffix) 0
--rb-size-total Set perf ring buffer size in total for all cpus (default 65k per cpu, allows K/M/G suffix) 0
--redaction-filters Redaction filters for events
--release-pinned-bpf Release all pinned BPF programs and maps in Tetragon BPF directory. Enabled by default. Set to false to disable true
--server-address gRPC server address (e.g. 'localhost:54321' or 'unix:///var/run/tetragon/tetragon.sock'). An empty address disables the gRPC server localhost:54321
--tracing-policy Tracing policy file to load at startup
--tracing-policy-dir Directory from where to load Tracing Policies /etc/tetragon/tetragon.tp.d
--username-metadata Resolve UIDs to user names for processes running in host namespace disabled
--verbose set verbosity level for eBPF verifier dumps. Pass 0 for silent, 1 for truncated logs, 2 for a full dump 0

Configuration precedence

Tetragon controlling settings can also be loaded from YAML configuration files according to this order:

  1. From the drop-in configuration snippets inside the following directories where each filename maps to one controlling setting and the content of the file to its corresponding value:

    • /usr/lib/tetragon/tetragon.conf.d/*
    • /usr/local/lib/tetragon/tetragon.conf.d/*

  2. From the configuration file /etc/tetragon/tetragon.yaml if available, overriding previous settings.

  3. From the drop-in configuration snippets inside /etc/tetragon/tetragon.conf.d/*, similarly overriding previous settings.

  4. If the config-dir setting is set, Tetragon loads its settings from the files inside the directory pointed by this option, overriding previous controlling settings. The config-dir is also part of Kubernetes ConfigMap.

When reading configuration from directories, each filename maps to one controlling setting. If the same controlling setting is set multiple times, then the last value or content of that file overrides the previous ones.

To summarize the configuration precedence:

  1. Drop-in directory pointed by --config-dir.

  2. Drop-in directory /etc/tetragon/tetragon.conf.d/*.

  3. Configuration file /etc/tetragon/tetragon.yaml.

  4. Drop-in directories:

    • /usr/local/lib/tetragon/tetragon.conf.d/*
    • /usr/lib/tetragon/tetragon.conf.d/*

Configuration examples

The examples/configuration/tetragon.yaml file contains example entries showing the defaults as a guide to the administrator. Local overrides can be created by editing and copying this file into /etc/tetragon/tetragon.yaml, or by editing and copying “drop-ins” from the examples/configuration/tetragon.conf.d directory into the /etc/tetragon/tetragon.conf.d/ subdirectory. The latter is generally recommended.

Each filename maps to a one controlling setting and the content of the file to its corresponding value. This is the recommended way.

Changing configuration example:

  • /etc/tetragon/tetragon.conf.d/bpf-lib with a corresponding value of:

    /var/lib/tetragon/

  • /etc/tetragon/tetragon.conf.d/log-format with a corresponding value of:

    text

  • /etc/tetragon/tetragon.conf.d/export-filename with a corresponding value of:

    /var/log/tetragon/tetragon.log

Restrict gRPC API access

The gRPC API supports unix sockets, it can be set using one of the following methods:

  • Use the --server-address flag:

    --server-address unix:///var/run/tetragon/tetragon.sock

  • Or use the drop-in configuration file /etc/tetragon/tetragon.conf.d/server-address containing:

    unix:///var/run/tetragon/tetragon.sock

Then to access the gRPC API with tetra client, set --server-address to point to the corresponding address:

sudo tetra --server-address unix:///var/run/tetragon/tetragon.sock getevents

Configure Tracing Policies location

Tetragon daemon automatically loads Tracing policies from the default /etc/tetragon/tetragon.tp.d/ directory. Tracing policies can be organized in directories such: /etc/tetragon/tetragon.tp.d/file-access, /etc/tetragon/tetragon.tp.d/network-access, etc.

The --tracing-policy-dir controlling setting can be used to change the default directory from where Tracing policies are loaded.

The --tracing-policy controlling setting can be used to specify the path of one tracing policy to load.

Last modified January 4, 2024: docs: use tetragon YAML docs data for daemon options reference (a97e4ee8)