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

The agent will then need to be restarted to make any changes take effect:

Native agent:

service dragent restart

Container agent:

docker restart sysdig-agent

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, or
  • Automatically passing any needed paramaters to the container agent at runtime, or
  • Making quick edits to the config file within the container, or
  • Mapping the config file to the host's file-system for easy editing.



Run Container With ADDITIONAL_CONF Flag

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  disabled: 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 Container Config at Runtime

In some situations, the configuration needed for an appcheck 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


In-Container Config Change

To quickly make small configuration changes to an existing and running container agent, enter 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

Exit the container and restart it with

 docker restart sysdig-agent 

to effect the changes.


Map 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.) and  issue docker restart sysdig-agent  to effect the changes.



For details on the options that can be put into the configuration file please see the User Guide and Frequently Asked Questions section found on

Have more questions? Submit a request