I need to troubleshoot an issue with an ECS container instance right after it boots. How do I enable Docker debug on boot of ECS-optimized AMIs via user data?

You might want to debug or troubleshoot an issue with an ECS container instance right after it boots (for example, a task that runs just after an instance is added to a cluster).

In order to enable Docker debug, you need to add the -D flag to the OPTIONS variable on /etc/sysconfig/docker.

However, you should not add a script to modify this variable because the Docker daemon is already started, and restarting it can interfere with the regular instance startup/registration/storage setup process or create a race condition.

Execute the modification of /etc/sysconfig/docker as a Cloud-Init boothook, which will execute before the Docker daemon is started. For more information, see Cloud Boothook.

If you set the first line of the user data to #cloud-boothook, Cloud-Init interprets it as a boothook and not as regular user-data. For example:


cloud-init-per once docker_debug echo 'OPTIONS="-D"' >> /etc/sysconfig/docker

However, if you need to also execute regular user data (for example, modify the ECS config or perform other changes), you must create multi-part user data. Multiple types of user data must be passed as multi-part. For more information, see CloudInit and the ECS documentation for Bootstrapping Container Instances. If your needs are complex, the multi-part userdata can be assembled by using the write-mime-multipart utility, which is part of the cloud-utils package.

Here is an example on how to assemble a multi-part user data that includes regular user data and a boothook:

Content-Type: multipart/mixed; boundary="==BOUNDARY=="
MIME-Version: 1.0

Content-Type: text/cloud-boothook; charset="us-ascii"

# Set Docker daemon options
cloud-init-per once docker_debug echo 'OPTIONS="-D"' >> /etc/sysconfig/docker

Content-Type: text/x-shellscript; charset="us-ascii"

# Set any ECS agent configuration options

cat >> /etc/ecs/ecs.config <<EOF


The boothook enables Docker debug, and the regular userdata enables ECS debug and sets the cluster name to join.

Note: This is also useful for modifying other Docker OPTIONS before the daemon starts.

Did this page help you? Yes | No

Back to the AWS Support Knowledge Center

Need help? Visit the AWS Support Center

Published: 2016-1-27

Updated: 2017-04-21