How do I use user data to automatically run a script with each restart of my Amazon EC2 Linux instance?

Short description

By default, user data commands and cloud-init directives run only during the first boot cycle when you launch an EC2 instance. To overwrite this configuration, use a Multipurpose Internet Mail Extensions (MIME) multi-part file to configure your user data commands and cloud-init directives. For more information, see MIME multi-part archive on the cloud-init website. Then, add the file to your instance.

Note: You can view the instance user data for any instance. However, to update the instance user data, you must stop your instance.

Resolution

Configure your instance for a stop and start

Note: When you stop and start an instance, the instance's public IP address changes. It's a best practice to use an Elastic IP address to route external traffic to your instance instead of a public IP address. If you use Amazon Route 53, then you might need to update the Route 53 DNS records when the public IP address changes. A stop and start is different from an instance reboot. For more information, see How EC2 instance stop and start works.

Before you stop and start your instance, take the following actions:

• If your instance uses an instance store, then save the volume data on the instance store to persistent storage. For example, you can save the data to Amazon Elastic Block Store (Amazon EBS) volumes or Amazon Simple Storage Service (Amazon S3) buckets.
  Important: Amazon EC2 deletes instance store data when you stop the instance.
• Create a snapshot of your Amazon EBS volume. If you experience issues, then you can use the snapshot to restore your instance.
• Temporarily remove the instance from its Amazon EC2 Auto Scaling group so that you don't accidentally terminate the instance when you stop it.
  Note: EC2 Auto Scaling might terminate stopped instances in an Auto Scaling group based on your scale-in protection settings. Instances that you launch with Amazon EMR, AWS CloudFormation, or AWS Elastic Beanstalk might be in an Auto Scaling group.
• Set the instance shutdown behavior to Stop to make sure that the instances don't terminate when you stop them.

Configure your instance to run the script on each restart

Complete the following steps:

1. Make sure that you installed the latest version of cloud-init on your instance. To view the latest cloud-init version, see Releases canonical/cloud-init on the GitHub website.
2. Verify that the AWS Identity and Access Management (IAM) policy for your user or role has the ec2:ModifyInstanceAttribute permission. For steps to modify your IAM policy, see Edit IAM policies (console).
3. Stop your instance.
4. Open the Amazon EC2 console.
5. Choose Instances, and then choose your instance
6. Choose Actions, and then select Instance settings.
7. Choose Edit user data, and then enter your user command as a MIME multi-part file:

   Content-Type: multipart/mixed; boundary="//"
   MIME-Version: 1.0
    
   --//
   Content-Type: text/cloud-config; charset="us-ascii"
   MIME-Version: 1.0
   Content-Transfer-Encoding: 7bit
   Content-Disposition: attachment; filename="cloud-config.txt"
    
   #cloud-config
   cloud_final_modules:
   - [scripts-user, always]
   --//
   Content-Type: text/x-shellscript; charset="us-ascii"
   MIME-Version: 1.0
   Content-Transfer-Encoding: 7bit
   Content-Disposition: attachment; filename="cloud-config.txt"
    
   #!/bin/bash
   /bin/echo "Hello World" >> /tmp/testfile.txt
   --//--

   Note: Replace the /bin/echo "Hello World" >> /tmp/testfile.txt section with the shell command that you want to run when the instance starts. The preceding example command writes Hello World to a testfile.txt file in a /tmp directory. With a MIME multi-part file, you can simultaneously add multiple content types to user data. The preceding command uses both text/cloud-config and text/x-shellscript content types. Set the scripts-user parameter to always so that the text/cloud-config content type overrides how frequently user data runs in the cloud-init package. The text/x-shellscript content type provides the user command to run the cloud-init cloud_final_modules module.
8. Choose Save.
9. Start your instance, and then validate that your script runs.
   Note: If your script didn't run as expected, then check the /var/log/cloud-init-output.log file for information you can use to debug your script. For more information, see How to debug cloud-init on the cloud-init website.

Related information

Run commands when you launch an EC2 instance with user data input

How do I run a command on a new EC2 Windows instance at launch?

How do I run a command on an existing EC2 Windows instance when I reboot or start the instance?

User-data formats on the cloud-init website