Configure the Agent

Out of the box, the Sysdig agent gathers and reports on a wide variety of predefined metrics. To collect additional metrics, configure the agent.

The file dragent.yaml defines metrics collection parameters. Modify dragent.yaml to configure the agent. How you configure dragent.yaml depends on whether the agent was installed:

In a Kubernetes environment.
In a non-orchestrated container, such as a Docker.
As a Linux package.

Follow the instructions on this page to implement configurations found in the Configuration Library.

Kubernetes

If Sysdig agent is installed in a Kubernetes environment with Helm, you can edit the dragent.yaml with Helm.

To edit dragent.yaml with Helm, you can:

Add configuration to values.yaml.
Use key-values as inline arguments with helm install.

For example, to edit dragent.yaml in Helm syntax:

helm install sysdig-agent \
  --namespace sysdig-agent \
  --set global.clusterConfig.name='my_cluster' \
  --set global.sysdig.tags.{tag_name_1}={tag_value_1} \
  --set global.sysdig.tags.{tag_name_2}={tag_value_2} \
  --set global.sysdig.tags.{tag_name_3}={tag_value_3} \
  sysdig/sysdig-deploy

where for each tag_name you have a specific tag_value like:

helm install sysdig-agent \
  --namespace sysdig-agent \
  --set global.clusterConfig.name='my_cluster' \
  --set global.sysdig.tags.linux=ubuntu \
  --set global.sysdig.tags.dept=dev \
  --set global.sysdig.tags.local=nyc \
  sysdig/sysdig-deploy

This command will be translated into the following:

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

For more details, including instruction on utilizing values.yaml see Sysdig Deploy.

Container

If Sysdig agent is installed in a non-orchestrated environment such as Docker, you can edit the dragent.yaml file in one or more of the following ways:

Mount the dragent.yaml file as a Docker volume inside the container.

docker run -v /home/admin-user/config-files/sysdig-agent/dragent.yaml:/opt/draios/etc/dragent.yaml ... quay.io/sysdig/agent

Pass parameters that will be appended to a dynamically generated dragent.yaml file via the ADDITIONAL_CONF environment variable.
```
docker run -e ADDITIONAL_CONF="<dragent.yaml parameters>" ... quay.io/sysdig/agent
```
If dragent.yaml is mounted as a Docker volume inside the container, the ADDITIONAL_CONF environment variable will be ignored.
Use environment variables such as COLLECTOR, ACCESS_KEY, TAGS, and so on to add or override specific parameters in dragent.yaml.
Pass environment variables directly to the agent such as SYSDIG_AGENT_DRIVER or SYSDIG_BPF_PROBE.

Edit dragent.yaml

Mount dragent.yaml as a container.
Log in to the host where the agent is installed.
Locate and open dragent.yaml.
If dragent.yaml is mounted inside an agent container as a Docker volume, it may be located anywhere on the host that the administrator finds convenient.
Edit the file using proper YAML syntax. See Examples.
For changes to take effect, restart the agent with the command:
```
docker restart sysdig-agent
```

docker run

Use the docker run command with -e ADDITIONAL_CONF="<VARIABLES>" where <VARIABLES> contains all the customized parameters you want to include.

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. You can do the conversion manually for short snippets. To convert longer portions of YAML, use echo|sed commands:

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

In a Bash shell, use echo and sed to convert to a single line:

echo '<YAML_CONTENT>' | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g'

Insert the resulting line into the docker run command or add it to the DaemonSet file as an ADDITIONAL_CONF.

Linux

If the Sysdig agent is installed in a Linux host via a .rpm or .deb package, edit dragent.yaml directly.

On .rpm installations, environment variables may be specified in /etc/sysconfig/dragent.
On .deb installations, environment variables may be specified in /etc/default/dragent.

The systemd supervisor does not support inline comments for environment variables. If you edit the file after setup, do not write comments on the same line where you define the environment variable.

The agent and its probe-loader shell script understand the following environment variables:

SYSDIG_AGENT_DRIVER (12.17.0 and newer)
SYSDIG_BPF_PROBE

Use one of the following:

Agent version 12.17.0 or newer
```
SYSDIG_AGENT_DRIVER=universal_ebpf
```
Agent versions before 12.17.0
```
export SYSDIG_BPF_PROBE=""
```

This environment file is sourced directly by the agent init script. For agent versions before 12.17.0, the export keyword is required.

Edit dragent.yaml

Log in to the host where the agent is installed.
Open /opt/draios/etc/dragent.yaml.
Edit the file using proper YAML syntax. See Examples.
For changes to take effect, restart the agent with the command:
```
service dragent restart
```

Examples

Disable StatsD Collection

This example shows how 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 IP addresses 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

statsd:
    enabled: false
    blacklisted_ports:
    - 6443

Single-Line Format

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

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

You can run a full agent startup Docker command in a single line as follows:

docker run
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=<ACCESS_KEY> \
  -e COLLECTOR=<COLLECTOR_ADDRESS> \
  -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 \
  quay.io/sysdig/agent

Add RabbitMQ App Check

This example helps you override the default configuration for a RabbitMQ app check.

YAML Format

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

Single-Line Format (echo | sed)

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

echo "app_checks:
  - name: rabbitmq
    pattern:
      port: 15672
    conf:
      rabbitmq_api_url: "http://localhost:15672/api/"
      rabbitmq_user: myuser
      rabbitmq_pass: mypassword
      queues:
        - 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"

Environment Variables Used by Entry Point Script for Non-Orchestrated Containers

Name	Value	Description
`ACCESS_KEY`	Your Sysdig access key.	Required.
`TAGS`	Meaningful tags you want applied to your instances.	Optional. For example: `tags: linux:ubuntu,dept:dev,local:nyc` See sysdig-agent-configmap.yaml.
`REGION`	The region associated with your Sysdig SaaS application.	Enter the SaaS region.
`COLLECTOR`	`<collector-hostname.com>`	Enter the hostname or IP address of the Sysdig collector service. Note that when used within `dragent.yaml`, it must be lowercase (`collector`). For SaaS regions, see SaaS Regions and IP Ranges. For SaaS applications, you must use either `REGION` or `COLLECTOR`.
`COLLECTOR_PORT`	`6443`	On-prem only. The port used by the Sysdig collector service. Default: `6443`.
`SECURE`	`true`	Use SSL/TLS to connect to collector service, defaults to `true`. Set to `false` to use plaintext HTTP to communicate with the collector service, (not recommended).
`CHECK_CERTIFICATE`	`true`	On-prem only. Set to `true` when using SSL/TLS to connect to the collector service and should check for a valid SSL/TLS certificate.
`ADDITIONAL_CONF`		Optional. A place to provide custom configuration values to the agent as environment variables. If `dragent.yaml` is mounted as a Docker volume inside the container, `ADDITIONAL_CONF` will be ignored.
`SYSDIG_PROBE_URL`		Optional. An alternative URL to download precompiled kernel modules.

Environment Variables Used by the Agent Probe-Loader Shell Script

Name	Value	Description
`SYSDIG_AGENT_DRIVER`	`kmod`, `universal_ebpf`, or `legacy_ebpf`	Optional. The syscall capture driver that is used by the agent. Agent defaults to `kmod` if this environment variable is not set.
`SYSDIG_BPF_PROBE`	`""` or a path to a custom-built eBPF object file.	Optional. Deprecated and superseded by `SYSDIG_AGENT_DRIVER`. The old environment variable that is used to force the agent to load the current eBPF driver. *Note:*The agent will exit with an error if `SYSDIG_AGENT_DRIVER` and `SYSDIG_BPF_PROBE` are set to conflicting values.

Name

Value

Description

SYSDIG_AGENT_DRIVER

kmod, universal_ebpf, or legacy_ebpf

Optional. The syscall capture driver that is used by the agent. Agent defaults to `kmod` if this environment variable is not set.

SYSDIG_BPF_PROBE

"" or a path to a custom-built eBPF object file.

Optional. Deprecated and superseded by SYSDIG_AGENT_DRIVER. The old environment variable that is used to force the agent to load the current eBPF driver.

Note:The agent will exit with an error if SYSDIG_AGENT_DRIVER and SYSDIG_BPF_PROBE are set to conflicting values.

Here is a sample Docker command using environment variables in an on-prem environment with a self-signed certificate:

docker run \
  --name sysdig-agent \
  --privileged \
  --net host \
  --pid host \
  -e ACCESS_KEY=<ACCESS_KEY> \
  -e COLLECTOR=<ONPREM_COLLECTOR_HOST> \
  -e COLLECTOR_PORT=6443 \
  -e CHECK_CERTIFICATE=false \
  -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 \
  quay.io/sysdig/agent

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.