Skip to content

Configuring Tracee

Tracee has many different options and settings that control how Tracee operates.

To learn about how to apply configuration to Tracee, please refer to the CLI or Kubernetes specific guides, depending on how you deploy Tracee.

A complete config file with all available options can be found here. Most of the options are documented in different sections in the documentation.

  • NOTE: The YAML examples can be translated to JSON as well

Common configurations

Output

  • --output (-o): Controls how and where the output is printed.

NOTE: You can view more in the output section.

YAML: 

output:
  - json

Server

  • --server: Sets options for the HTTP and/or gRPC servers.

CLI Examples: 

# Address configuration
tracee --server http-address=:3366
tracee --server grpc-address=unix:/var/run/tracee.sock

# HTTP features (boolean flags)
tracee --server metrics --server healthz --server pprof

YAML: 

server:
  http-address: ":3366"
  grpc-address: "unix:/var/run/tracee.sock"
  metrics: true
  healthz: true
  pprof: true
  pyroscope: true

Process Tree

  • --proctree (-t): Controls process tree options.

NOTE: You can view more in the Process Tree section.

YAML: 

proctree:
  - process

Install Path

  • --install-path: Specifies the directory where Tracee will install or look for its resources. If not specified, the default installation directory is /tmp/tracee.

YAML: 

install-path: /opt/tracee

NOTE: This option is useful when running Tracee in environments where /tmp is not suitable or secure.

Log

  • --log (-l): Controls the verbosity level of Tracee's logging system. The default log level is info.

NOTE: You can view more in the Tracee Logs section.

YAML: 

log:
  - level: debug

Containers

  • To disable container enrichment use: --containers enrich=false.

YAML: 

containers:
  enrich: false

NOTE: You can view more in the containers section.

  • --containers: Configures container enrichment and runtime sockets. For example, to configure runtime sockets:

YAML: 

containers:
  sockets:
    - runtime: docker
      socket: /var/run/docker.sock

DNS Cache

  • --dnscache: Enables DNS caching in Tracee.

NOTE: You can view more in the DNS Cache section.

YAML: 

dnscache: enable

Capabilities

  • --capabilities (-C): Define specific capabilities for Tracee to run with. This allows you to either bypass, add, or drop certain capabilities based on your security and operational needs.

NOTE: You can view more in the Tracee Capabilities section

YAML: 

capabilities:
  - add: 
      - CAP_SYS_ADMIN
  - drop: 
      - CAP_NET_RAW

NOTE: Capabilities are Linux-specific permissions that control which privileged operations a program can perform.

Buffer and Cache

  • --perf-buffer-size (-b): Specifies the size of the internal perf ring buffer in pages.

Default: 1024 (4 MB)

YAML: 

perf-buffer-size: 2048

  • --blob-perf-buffer-size: Specifies the size of the internal perf ring buffer used to send blobs from the kernel.

Default: 1024 (4 MB)

YAML: 

blob-perf-buffer-size: 2048

  • --pipeline-channel-size: Specifies the size of each pipeline stage's output channel.

Default: 1000

YAML: 

pipeline-channel-size: 2048