Understand the Agent Configuration
Out of the box, the Sysdig agent will gather and report on a wide variety of predefined metrics. It can also accommodate any number of custom parameters for additional metrics collection.
The agent relies on a configuration file named dragent.yaml
to define metrics collection parameters. This file is located in the /opt/draios/etc/
directory. Configuration parameters may be added directly in YAML format as key-value pairs.
The agent and its probe-loader shell script also understand the following environment variables:
SYSDIG_AGENT_DRIVER
(12.17.0 and newer)SYSDIG_BPF_PROBE
The contents of dragent.yaml
and the agent’s environment variables may be specified in different ways depending on how the agent was installed.
This document describes how to modify dragent.yaml
and the agent’s environment variables.
Environments
For more information about configuring each of the three environments listed in this section, see Edit the Configuration File.
Kubernetes
If Sysdig agent is installed in a Kubernetes environment, you can edit the dragent.yaml
file using one of the following options:
values.yaml
ConfigMap
sysdig-deploy
Helm chart
Container
If Sysdig agent is installed in a non-orchestrated environment such as Docker, you can edit the dragent.yaml
file using one or more of the following options:
A
dragent.yaml
file mounted 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 theADDITIONAL_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, theADDITIONAL_CONF
environment variable will be ignored.Use environment variables such as
COLLECTOR
,ACCESS_KEY
,TAGS
, and so on to add or override specific parameters indragent.yaml
.Pass environment variables directly to the agent such as
SYSDIG_AGENT_DRIVER
orSYSDIG_BPF_PROBE
.
Linux package
If the Sysdig agent is installed in a Linux host via a .rpm
or .deb
package, edit /opt/draios/etc/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
.
Use one of the following:
SYSDIG_AGENT_DRIVER=universal_ebpf # Agent version 12.17.0 or newer
export SYSDIG_BPF_PROBE=""
This environment file is sourced directly by the agent init script. For agent versions 12.16.x and older, the export
keyword is required.
Edit the Configuration File
dragent.yaml
Log in to the host where the agent is installed.
Open
/opt/draios/etc/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 the examples at the bottom of the page.
Restart the agent for changes to take effect.
Linux package:
service dragent restart
Non-orchestrated container:
docker restart sysdig-agent
configmap.yaml
If you install the agent using DaemonSets on a Kubernetes cluster, you use configmap.yaml
to connect with and manipulate the underlying dragent.yaml
file.
Use the following ways to add parameters to configmap.yaml
:
Directly edit
configmap.yaml
in YAML as key-value pairs.Use environment variables such as
ADDITIONAL_CONF
.
You can edit the files locally and apply the changes with kubectl -f
:
Open the
configmap.yaml
file.Edit the file as needed.
Apply the changes:
kubectl apply -f sysdig-agent-configmap.yaml
All the running agents will automatically pick the new configuration after Kubernetes pushes the changes across all the nodes in the cluster.
docker run
Run 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
andsed
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 anADDITIONAL_CONF
.
Examples
Disable StatsD Collection
This example shows how to turn off the 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"
helm install
If you installed the Sysdig agent in Kubernetes using the Helm chart, then no configmap.yaml
file was downloaded. You can edit dragent.yaml
using the 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
Environment Variables Used by Entry Point Script for Non-Orchestrated Containers
Name | Value | Description |
---|---|---|
| Your Sysdig access key. | Required. |
| Meaningful tags you want applied to your instances. | Optional. For example:
|
| The region associated with your Sysdig SaaS application. | Enter the SaaS region. |
|
| Enter the hostname or IP address of the Sysdig collector service. Note that when used within For SaaS regions, see SaaS Regions and IP Ranges. For SaaS applications, you must use either `REGION` or `COLLECTOR`. |
|
| On-prem only. The port used by the Sysdig collector service. Default: |
|
| Use SSL/TLS to connect to collector service, defaults to |
|
| On-prem only. Set to |
| 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. | |
| Optional. An alternative URL to download precompiled kernel modules. |
Environment Variables Used by the Agent Probe-Loader Shell Script
Name | Value | Description |
---|---|---|
| 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. |
|
| Optional. Deprecated and superseded by Note:The agent will exit with an error if |
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.