How can I edit the agent's configuration file?

Customizing the Sysdig agent with optional parameters is performed by editing the agent's user settings configuration file and restarting the agent. For both a native Linux agent installation and the container agent installation, edit the file (locally or in the container):  /opt/draios/etc/dragent.yaml

If the agent's dragent.yaml file is edited, changes will take effect within 5 seconds after saving the file as the agent will detect the change and automatically restart.  The default configuration file (dragent.default.yaml) shows the sequence and interval used when checking for changes:

check_frequency_s: 5
- /opt/draios/etc/dragent.yaml
- /opt/draios/etc/kubernetes/config/dragent.yaml
- /opt/draios/etc/kubernetes/secrets/access-key

Note that there actually two possible locations for the dragent.yaml file depending on how the agent was deployed. Only the ./etc/dragent.yaml version is user-editable since the Kubernetes version is controlled by the agent daemonset (V2) that roles out the agent in Kubernetes environments using config maps.


Kubernetes Daemonsets

If the agent is instrumented via Kubernetes daemonsets, make permanent changes by using our template manifest files to add configurations: 

If using the daemonset V1 template, you will list additional configurations under the "ADDITIONAL_CONF:" section of the template.  When using the daemonset V2 template, append new configurations to the sysdig-agent-configmap.yaml config map file which the V2 template references.


Non-Kubernetes Methods

Because the container agent's footprint is kept as small as possible and options for easily editing its configuration file are more limited, the remainder of this article will show how to add or edit options for the containerized agent using several methods:

  • Starting the container agent with any needed parameters
  • Automatically passing any needed paramaters to the container agent at runtime
  • Making quick edits to the config file within the running container
  • Mapping the config file to the host's file-system for easy editing

For more detailed agent configuration file information, refer to



With this method, modify the container agent's Docker run command by adding -e ADDITIONAL_CONF="[VARIABLES]" substituting [variables] with the content of the changes you wish to include. Content must be valid yaml code, use the escape \n parameter for new lines and adhere to proper indent requirements.

The example Docker run command below will insert two optional parameters to turn off StatsD collection and blacklist port 6666.  The option to add to the Docker run command is:

-e ADDITIONAL_CONF="statsd:\n  enabled: false\nblacklisted_ports:\n  - 6666"

Complete container agent example startup 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\nblacklisted_ports:\n  - 6666" -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 sysdig/agent

The dragent.yaml configuration file will have the additional parameters added to it and the Sysdig agent will start with them in effect. 

Here is a more complex example with a configuration override for the RabbitMQ application check script. We can echo the YAML-formatted configuration through the `sed` command to convert it to the format required by the ADDITIONAL_CONF parameter:

From a bash shell, issue the echo command:

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'

which will yield the string to use with -ADDITIONAL_CONF in the docker run command above:

"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"


Automatic Application Check Configuration at Runtime

In some situations, the configuration needed for an application check may depend on the containers that the agent finds itself monitoring at runtime. For example, in a PaaS/CaaS situation, you may have multiple versions of a Cassandra container running, and the agent will need a unique configuration to monitor each one. In this case, it is possible for the application container to pass config information directly to the Sysdig agent container at runtime. Please see: Customizing App-Checks Per Container


Running Config Change

To quickly make small configuration changes to an existing running containerzed agent, step into the sysdig-agent container directly with:

docker exec -it sysdig-agent bash

Then issue an echo command to append a needed parameter to the dragent.yaml file. This example changes the agent's connection port to 80:

echo collector_port: 80 >> /opt/draios/etc/dragent.yaml 

You can also use the docker cp command to copy the config file out of and in to the sysdig-agent  container to make changes using a preferred editor on the host:

docker cp sysdig-agent:/opt/draios/etc/dragent.yaml .
vi ./dragent.yaml
docker cp ./dragent.yaml sysdig-agent:/opt/draios/etc/dragent.yaml

Note: that you will not be able to change any environment variables (ex: access key or tags) that were specified in the docker run command with this method.


Mapping The Config File To The Local Host Using '-v'

This method is useful if you are testing a configuration or need to make frequent changes.  The agent's configuration file is stored on the local host's file system and will remain even if the agent's container is removed. You can easily edit the config file with a host-based editor, restarting the agent to make the changes take effect as usual.

If your containerized agent is already installed and running, open a shell on your host and copy the user settings configuration file to the host's local file system:

mkdir /opt/draios/etc
docker cp sysdig-agent:/opt/draios/etc/dragent.yaml /opt/draios/etc/dragent.yaml

Otherwise if no container exists yet, create a new empty configuration file before creating the agent container:

mkdir -vp /opt/draios/etc
touch /opt/draios/etc/dragent.yaml

Stop and remove any previous agent container (docker kill/rm sysdig-agent) and start a new one mapping to the host based config file using the -v flag:

docker run --name sysdig-agent --privileged --net host --pid host -e ACCESS_KEY=1234-your-key-here-1234 -e TAGS=dept:sales,local:NYC -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 -v /opt/draios/etc/dragent.yaml:/opt/draios/etc/dragent.yaml:rw sysdig/agent

If your config file was already populated with an access key or tags, they will not be overridden. Only missing tags or keys will be added if specified on the docker run command.

From this point onward, you can modify the dragent.yaml file as desired from the host (adding new tags, app-checks or JMX entries, etc.).



Have more questions? Submit a request