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

Short description

To run a command when you start or reboot your EC2 instance, configure a user data script to run when you reboot or start the instance.

Based on your operating system (OS), your configuration uses the following agents to process user data:

• Windows Server 2012 R2 and earlier uses EC2Config.
• Windows Server 2016 and 2019 uses EC2Launch.
• Windows Server 2022 and 2025 uses EC2Launch v2.

Note: To update your instance's user data with the Amazon EC2 console, you must stop the instance. However, for EC2Launch v2, you can use a YAML script to update the instance without a stop and start.

Resolution

(EC2Launch v2 only) Use a YAML script to update your instance without a stop and start

Use Remote Desktop Protocol (RDP) to connect to your Windows instance.

To run the script at each reboot or restart, update the agent-config.yml file. Add the executeScript task to stage: postReady and set frequency to always.

Example YAML file:

version: "1.0"
config:
  - stage: boot
    tasks:
      - task: extendRootPartition
  - stage: preReady
    tasks:
      - task: activateWindows
        inputs:
          activation:
            type: amazon
      - task: setDnsSuffix
        inputs:
          suffixes:
            - $REGION.ec2-utilities.amazonaws.com
      - task: setAdminAccount
        inputs:
          password:
            type: random
      - task: setWallpaper
        inputs:
          attributes:
            - hostName
            - instanceId
            - privateIpAddress
            - publicIpAddress
            - ipv6Address
            - instanceSize
            - availabilityZone
            - architecture
          path: C:\Windows\Web\Wallpaper\Windows\img0.jpg
  - stage: postReady
    tasks:
      - task: startSsm
      - task: executeScript
        inputs:
          - frequency: always
            type: powershell
            runAs: localSystem
            content: |-
                New-Item -Path 'C:\PowerShellTest.txt' -ItemType File

To run the script only at the next instance reboot or restart, open C:\ProgramData\Amazon\EC2Launch\state, and then delete the .run-once file. Update the agent-config.yml file to add the executeScript task to stage: postReady and set frequency to once.

Important: When you delete the .run-once file, the instance's local administrator password changes at restart. If you launched the instance without a key pair or you lost the key pair, then you might lose access to your instance on restart.

For more information about command syntax, see Syntax for YAML configuration scripts.

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.

Update your instance's user data

Add your commands as a script to the user data for your instance. For information about how to configure the script to run on each reboot or restart, see Run scripts during subsequent reboots or starts.

Note: To run the script at each start or reboot for EC2Launch v2, add a YAML script as the executeScript task or an XML script. For YAML, set frequency to always, and for XML scripts, add the <persist>true</persist> tag. For all agents, enclose the user data in a tag that defines whether the command runs in Command Prompt or Windows PowerShell. For more information about command syntax, see Syntax for Windows PowerShell scripts.

Troubleshoot issues

To troubleshoot issues, check the standard output and standard error streams in the EC2Config, EC2Launch, or EC2Launch v2 log files.

To find the log files, check the following locations:

• For EC2Config, check C:\Program Files\Amazon\Ec2ConfigService\Logs\Ec2Config.log.
• For EC2Launch, check C:\ProgramData\Amazon\EC2-Windows\Launch\Log\UserdataExecution.log.
• For EC2Launch v2, check C:\ProgramData\Amazon\EC2Launch\log\agent.log.

Related information

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