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.

FlagUsageDefault Value
--bpf-libLocation of Tetragon libs (btf and bpf files)/var/lib/tetragon/
--btfLocation of btf
--config-dirConfiguration directory that contains a file for each option
--cpuprofileStore CPU profile into provided file
--data-cache-sizeSize of the data events cache1024
--debugEnable debug messages. Equivalent to '--log-level=debug'false
--disable-kprobe-multiAllow to disable kprobe multi interfacefalse
--enable-export-aggregationEnable JSON export aggregationfalse
--enable-k8s-apiAccess Kubernetes API to associate Tetragon events with Kubernetes podsfalse
--enable-msg-handling-latencyEnable metrics for message handling latencyfalse
--enable-pid-set-filterEnable pidSet export filters. Not recommended for production usefalse
--enable-pod-infoEnable PodInfo custom resourcefalse
--enable-policy-filterEnable policy filter code (beta)false
--enable-policy-filter-debugEnable policy filter debug messagesfalse
--enable-process-ancestorsInclude ancestors in process exec eventstrue
--enable-process-credEnable process_cred eventsfalse
--enable-process-nsEnable namespace information in process_exec and process_kprobe eventsfalse
--enable-tracing-policy-crdEnable TracingPolicy and TracingPolicyNamespaced custom resourcestrue
--event-queue-sizeSet the size of the internal event queue.10000
--export-aggregation-buffer-sizeAggregator channel buffer size10000
--export-aggregation-window-sizeJSON export aggregation time window15s
--export-allowlistJSON export allowlist
--export-denylistJSON export denylist
--export-file-compressCompress rotated JSON export filesfalse
--export-file-max-backupsNumber of rotated JSON export files to retain5
--export-file-max-size-mbSize in MB for rotating JSON export files10
--export-file-permAccess permissions on JSON export files600
--export-file-rotation-intervalInterval at which to rotate JSON export files in addition to rotating them by size0s
--export-filenameFilename for JSON export. Disabled by default
--export-rate-limitRate limit (per minute) for event export. Set to -1 to disable-1
--expose-kernel-addressesExpose real kernel addresses in events stack tracesfalse
--field-filtersField filters for event exports
--force-large-progsForce loading large programs, even in kernels with < 5.3 versionsfalse
--force-small-progsForce loading small programs, even in kernels with >= 5.3 versionsfalse
--generate-docsGenerate documentation in YAML format to stdoutfalse
--gops-addressgops server address (e.g. 'localhost:8118'). Disabled by default
--helphelp for tetragonfalse
--k8s-kubeconfig-pathAbsolute path of the kubernetes kubeconfig file
--kernelKernel version
--kmodsList of kernel modules to load symbols from[]
--log-formatSet log formattext
--log-levelSet log levelinfo
--memprofileStore MEM profile into provided file
--metrics-label-filterComma-separated list of enabled metric labels. (e.g. "namespace,workload,pod,binary") By default all labels are enabled.
--metrics-serverMetrics server address (e.g. ':2112'). Disabled by default
--netns-dirNetwork namespace dir/var/run/docker/netns/
--pprof-addrProfile via pprof http
--process-cache-sizeSize of the process cache65536
--procfsLocation of procfs to consume existing PIDs/proc/
--rb-queue-sizeSet size of channel between ring buffer and sensor go routines (default 65k, allows K/M/G suffix)65535
--rb-sizeSet perf ring buffer size for single cpu (default 65k, allows K/M/G suffix)0
--rb-size-totalSet perf ring buffer size in total for all cpus (default 65k per cpu, allows K/M/G suffix)0
--release-pinned-bpfRelease all pinned BPF programs and maps in Tetragon BPF directory. Enabled by default. Set to false to disabletrue
--server-addressgRPC server address (e.g. 'localhost:54321' or 'unix:///var/run/tetragon/tetragon.sock'localhost:54321
--tracing-policyTracing policy file to load at startup
--tracing-policy-dirDirectory from where to load Tracing Policies/etc/tetragon/tetragon.tp.d
--verboseset verbosity level for eBPF verifier dumps. Pass 0 for silent, 1 for truncated logs, 2 for a full dump0

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.