Understand the Agent Configuration

Out of the box, the Sysdig agent will gather and report on a wide variety of pre-defined metrics. It can also accommodate any number of custom parameters for additional metrics collection.

The agent relies on a pair of configuration files to define metrics collection parameters:


The core configuration file. You can look at it to understand more about the default configurations provided.

Location: /opt/draios/etc/dragent.default.yaml.

CAUTION. This file should never be edited.

dragent.yaml or configmap.yaml (Kubernetes)

The configuration file where parameters can be added, either directly in YAML as name/value pairs, or using environment variables such as ADDITIONAL_CONFLocation: /opt/draios/etc/dragent.yaml.

The dragent.yaml file can be accessed and edited in several ways, depending on how the agent was installed. This document describes how to modify dragent.yaml.

One additional file, dragent.auto.yaml is also created and used in special circumstances. See Optional: Agent Auto-Config for more detail.

Access and Edit the Configuration File

There are various ways to add or edit parameters indragent.yaml.

Option 1: With dragent.yaml (for testing)

It is possible to edit the container’s file directly on the host.

Add parameters directly in YAML.

  1. Access dragent.yamldirectly at"/opt/draios/etc/dragent.yaml."

  2. Edit the file. Use proper YAML syntax.

    See the examples at the bottom of the page.

  3. Restart the agent for changes to take effect

  • Native agent: service dragent restart

  • Container agent: docker restart sysdig-agent

Option 2: With configmap.yaml (Kubernetes)

Configmap.yaml is the configuration file where parameters can be added, either directly in YAML as name/value pairs, or using environment variables such as ‘ADDTIONAL_CONF."

If you install agents as DaemonSets on a system running Kubernetes, you use configmap.yaml to connect with and manipulate the underlyingdragent.yamlfile.

See Agent Install: Kubernetes for more information.

Add parameters directly in YAML.

Edit the files locally and apply with the changes withkubectl -f.

  1. Access theconfigmap.yaml.

  2. Edit the file as needed.

  3. Apply the changes:

    kubectl apply -f sysdig-agent-configmap.yaml

Running agents will automatically pick the new configuration after Kubernetes pushes the changes across all the nodes in the cluster.

Option 3: With Docker Run (Docker)

Add -e ADDITIONAL_CONF="<VARIABLES>" to a Docker run command, where <VARIABLES> contains all the customized parameters you want to include, in a single-line format.

Convert YAML Parameters to Single-Line Format

To insert ADDITIONAL_CONF parameters in a Docker run command or a daemonset file, you must convert the YAML code into a single-line format.

You can do the conversion manually for short snippets. To convert longer portions of YAML, use echo|sed commands.

In earlier versions, the Sysdig Agent connected to port 6666. This behavior has been deprecated, as the Sysdig agent now connects to port 6443.

The basic procedure:

  1. Write your configuration in YAML, as it would be entered directly in dragent.yaml.

  2. In a bash shell, use echo and sed to convert to a single line.

    sed script: echo "" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

  3. Insert the resulting line into a Docker run command or add it to the daemonset file as an ADDITIONAL_CONF.

Example: Simple

Insert parameters to turn off StatsD collection and blacklist port 6443.

Sysdig agent uses port 6443 for both inbound and outbound communication with the Sysdig backend. The agent initiates a request and keeps a connection open with the Sysdig backend for the backend to push configurations, Falco rules, policies, and so on. Ensure that you allow the agents’ inbound and outbound communication on TCP 6443 from the respective IPs associated with your SaaS Regions. Note that you are allowing the agent to send communication outbound on TCP 6443 to the inbound IP ranges listed in the SaaS Regions.

YAML format

    enabled: false
    - 6443

Single-line format (manual)

Use spaces, hyphens, and \n correctly when manually converting to a single line:

ADDITIONAL_CONF="statsd:\n enabled: false\n blacklisted_ports:\n - 6443"

Here the single line is incorporated into a full agent startup Docker command.

docker run
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=1234-your-key-here-1234 \
  -e TAGS=dept:sales,local:NYC \
  -e ADDITIONAL_CONF="statsd:\n    enabled: false\n    blacklisted_ports:\n    - 6443" \
  -v /var/run/docker.sock:/host/var/run/docker.sock \
  -v /dev:/host/dev \
  -v /proc:/host/proc:ro \
  -v /boot:/host/boot:ro \
  -v /lib/modules:/host/lib/modules:ro \
  -v /usr:/host/usr:ro \
Example: Complex

Insert parameters to override the default configuration for a RabbitMQ app check.

YAML format

  - name: rabbitmq
      port: 15672
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
        - MyQueue1
        - MyQueue2

Single-line format (echo |sed)

From a bash shell, issue the echo command and sed script.

echo "app_checks:
  - name: rabbitmq
      port: 15672
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
        - MyQueue1
        - MyQueue2
" | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

This results in the single-line format to be used with ADDITIONAL_CONF in a Docker command or daemonset file.

"app_checks:\n - name: rabbitmq\n  pattern:\n    port: 15672\n  conf:\n    rabbitmq_api_url: http://localhost:15672/api/\n    rabbitmq_user: myuser\n    rabbitmq_pass: mypassword\n    queues:\n      - MyQueue1\n      - MyQueue2\n"

Option 4: With Helm Format

If you installed the Sysdig agent in Kubernetes Using a Helm chart, then no configmap.yaml file was downloaded. You edit dragent.yaml using Helm syntax:


$ helm install \
    --namespace sysdig-agent \
    --set agent.sysdig.settings.tags='linux:ubuntu\,dept:dev\,local:nyc' \
    --set global.clusterConfig.name='my_cluster' \

Will be transformed into

 dragent.yaml: |
  tags: linux:ubuntu,dept:dev,local:nyc
  k8s_cluster_name: my_cluster

Table 1: Environment Variables for Agent Config File





<your Sysdig access key>



<meaningful tags you want applied to your instances>

Optional. These are displayed in Sysdig Monitor for ease of use.

For example:

tags: linux:ubuntu,dept:dev,local:nyc

See sysdig-agent-configmap.yaml.


The region associated with your Sysdig application.

Enter the SaaS region.


<collector-hostname.com> or 111.222.333.400

Enter the host name or IP address of the Sysdig collector service. Note that when used within dragent.yaml, must be lowercase collector.

For SaaS regions, see: SaaS Regions and IP Ranges.



On-prem only. The port used by the Sysdig collector service; default 6443.



On-prem only. If using SSL/TLS to connect to collector service value = "true" otherwise "false."



On-prem only. Set to "true" when using SSL/TLS to connect to the collector service and should check for valid SSL/TLS certificate.


Optional. A place to provide custom configuration values to the agent as environment variables .


Optional. An alternative URL to download precompiled kernel module.

Sample Docker Command Using Variables

docker run \
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=3e762f9a-3936-4c60-9cf4-c67e7ce5793b \
  -e COLLECTOR=mycollector.elb.us-west-1.amazonaws.com \
  -e COLLECTOR_PORT=6443 \
  -e TAGS=my_tag:some_value \
  -e ADDITIONAL_CONF="log:\n file_priority: debug\n console_priority: error" \
  -v /var/run/docker.sock:/host/var/run/docker.sock \
  -v /dev:/host/dev \
  -v /proc:/host/proc:ro \
  -v /boot:/host/boot:ro \
  -v /lib/modules:/host/lib/modules:ro \
  -v /usr:/host/usr:ro \
  --shm-size=350m \

Last modified September 23, 2022