Task definitions for EC2Launch v2 startup tasks
Each task that EC2Launch v2 runs during launch or statup has its own set of properties and requirements. Task details include settings for how often a task runs – once, or always, what stage of the agent boot process it runs in, syntax, and YAML document examples. For more information, review the task details shown in this reference.
EC2Launch v2 Tasks
activateWindows
Activates Windows against a set of AWS KMS servers. Activation is skipped if the instance is detected as Bring-Your-Own-License (BYOL).
Frequency — once
AllowedStages — [PreReady]
Inputs —
activation
: (map)
type
: (string) activation type to use, set to
amazon
Example
task: activateWindows inputs: activation: type: amazon
enableJumboFrames
Enables Jumbo Frames, which increase the maximum transmission unit (MTU) of the network adapter. For more information, see Jumbo frames (9001 MTU).
Frequency — always
AllowedStages — [PostReady, UserData]
Inputs — none
Example
task: enableJumboFrames
enableOpenSsh
Enables Windows OpenSSH and adds the public key for the instance to the authorized keys folder.
Frequency — once
AllowedStages — [PreReady, UserData]
Inputs — none
Example
The following example shows how to enable OpenSSH on an instance, and to add the public key for the instance to the authorized keys folder. This configuration works only on instances running Windows Server 2019 and later versions.
task: enableOpenSsh
executeProgram
Runs a program with optional arguments and a specified frequency.
Stages: You can run the executeProgram
task during the PreReady
, PostReady
, and UserData
stages.
Frequency: configurable, see Inputs.
- Inputs
-
This section contains one or more programs for the executeProgram task to run (inputs). Each input can include the following configurable settings:
- frequency (string)
-
(Required) Specify exactly one of the following values:
-
once
-
always
-
- path (string)
-
(Required) The file path for the executable to run.
- arguments (list of strings)
-
(Optional) A comma separated list of arguments to provide to the program as input.
- runAs (string)
-
(Required) Must be set to
localSystem
- Output
-
All of the tasks write logfile entries to the
agent.log
file. Additional output from theexecuteProgram
task is stored separately in a dynamically named folder, as follows:%LocalAppData%\Temp\
EC2Launch#########
\outputfilename.tmp
The exact path to the output files is included in the
agent.log
file, for example:Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\ExecuteProgramInputs.tmp Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Output files for the
executeProgram
taskExecuteProgramInputs.tmp
-
Contains the path for the executable, and all of the input parameters that the
executeProgram
task passes to it when it runs. Output.tmp
-
Contains runtime output from the program that the
executeProgram
task runs. Err.tmp
-
Contains runtime error messages from the program that the
executeProgram
task runs.
- Examples
-
The following examples show how to run an executable file from a local directory on an instance with the
executeProgram
task.Example 1: Setup executable with one argument
This example shows an
executeProgram
task that runs a setup executable in quiet mode.task: executeProgram inputs: - frequency: always path: C:\Users\Administrator\Desktop\setup.exe arguments: ['-quiet']
Example 2: VLC executable with two arguments
This example shows an
executeProgram
task that runs a VLC executable file with two arguments passed as input parameters.task: executeProgram inputs: - frequency: always path: C:\vlc-3.0.11-win64.exe arguments: ['/L=1033','/S'] runAs: localSystem
executeScript
Runs a script with optional arguments and a specified frequency. Script behavior depends on what mode the agent runs the scripts in – inline, or detached.
- Inline (default)
-
The EC2Launch v2 agent runs scripts one at a time (
detach: false
). This is the default setting.Note
When your inline script issues a reset or sysprep command, it runs immediately and resets the agent. The current task finishes, then the agent shuts down without running any further tasks.
For example, if the task that issues the command would have been followed by a
startSsm
task (included by default after user data runs), the task doesn't run and the Systems Manager service never starts. - Detached
-
The EC2Launch v2 agent runs scripts concurrently with other tasks (
detach: true
).Note
When your detached script issues a reset or sysprep command, those commands wait for the agent to finish before they run. Tasks after the executeScript will still run.
Stages: You can run the executeScript
task during the PreReady
, PostReady
, and UserData
stages.
Frequency: configurable, see Inputs.
- Inputs
-
This section contains one or more scripts for the executeScript task to run (inputs). Each input can include the following configurable settings:
- frequency (string)
-
(Required) Specify exactly one of the following values:
-
once
-
always
-
- type (string)
-
(Required) Specify exactly one of the following values:
-
batch
-
powershell
-
- arguments (list of strings)
-
(Optional) A list of string arguments to pass to the shell. This parameter isn't supported for
type: batch
. If no arguments are passed, EC2Launch v2 adds the following argument by default:-ExecutionPolicy Unrestricted
. - content (string)
-
(Required) Script content.
- runAs (string)
-
(Required) Specify exactly one of the following values:
-
admin
-
localSystem
-
- detach (Boolean)
-
(Optional) The EC2Launch v2 agent defaults to run scripts one at a time (
detach: false
). To run the script concurrently with other tasks, set the value totrue
(detach: true
).Note
Script exit codes (including
3010
) have no effect whendetach
is set totrue
.
- Output
-
All of the tasks write logfile entries to the
agent.log
file. Additional output from script that theexecuteScript
task runs is stored separately in a dynamically named folder, as follows:%LocalAppData%\Temp\
EC2Launch#########
\outputfilename.ext
The exact path to the output files is included in the
agent.log
file, for example:Program file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\UserScript.ps1 Output file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Output.tmp Error file is created at: C:\Windows\system32\config\systemprofile\AppData\Local\Temp\EC2Launch123456789\Err.tmp
Output files for the
executeScript
taskUserScript.
ext
-
Contains the script that the
executeScript
task ran. The file extension depends on the type of script you specified in thetype
parameter for theexecuteScript
task, as follows:-
If the type is
batch
, then the file extension is.bat
. -
If the type is
powershell
, then the file extension is.ps1
.
-
Output.tmp
-
Contains runtime output from the script that the
executeScript
task runs. Err.tmp
-
Contains runtime error messages from the script that the
executeScript
task runs.
- Examples
-
The following examples show how to run an inline script with the
executeScript
task.Example 1: Hello world output text file
This example shows an
executeScript
task that runs a PowerShell script to create a "Hello world" text file on theC:
drive.task: executeScript inputs: - frequency: always type: powershell runAs: admin content: |- New-Item -Path 'C:\PowerShellTest.txt' -ItemType File Set-Content 'C:\PowerShellTest.txt' "Hello world"
Example 2: Run two scripts
This example shows that the
executeScript
task can run more than one script, and the script type doesn't necessarily need to match.The first script (
type: powershell
) writes a summary of the processes that are currently running on the instance to a text file located on theC:
drive.The second script (
batch
) writes the system information to theOutput.tmp
file.task: executeScript inputs: - frequency: always type: powershell content: | Get-Process | Out-File -FilePath C:\Process.txt runAs: localSystem - frequency: always type: batch content: | systeminfo
Example 3: Idempotent system configuration with reboots
This example shows an
executeScript
task that runs an idempotent script to perform the following system configuration with a reboot between each step:-
Rename the computer.
-
Join the computer to the domain.
-
Enable Telnet.
The script ensures that each operation runs one time only. This prevents a reboot loop and makes the script idempotent.
task: executeScript inputs: - frequency: always type: powershell runAs: localSystem content: |- $name = $env:ComputerName if ($name -ne $desiredName) { Rename-Computer -NewName $desiredName exit 3010 } $domain = Get-ADDomain if ($domain -ne $desiredDomain) { Add-Computer -DomainName $desiredDomain exit 3010 } $telnet = Get-WindowsFeature -Name Telnet-Client if (-not $telnet.Installed) { Install-WindowsFeature -Name "Telnet-Client" exit 3010 }
-
extendRootPartition
Extends the root volume to use all of the available space on the disk.
Frequency — once
AllowedStages — [Boot]
Inputs — none
Example
task: extendRootPartition
initializeVolume
Initializes empty volumes that are attached to the instance so that they're
activated and partitioned. The launch agent skips initialization if it detects
that the volume is not empty. A volume is considered empty if the first
4 KiB of the volume are empty, or if the volume doesn't have a Windows-recognizable drive layout
The letter
input parameter is always applied when this task runs,
regardless of whether the drive is already initialized.
The initializeVolume
task performs the following actions.
-
Set disk attributes
offline
andreadonly
to false. -
Create a partition. If no partition type is specified in the
partition
input parameter, the following defaults apply:-
If the disk size is smaller than 2 TB, set the partition type to
mbr
. -
If the disk size is 2 TB or larger, set the partition type to
gpt
.
-
-
Format the volume as NTFS.
-
Set the volume label as follows:
-
Use the value of the
name
input parameter, if specified. -
If the volume is ephemeral, and no name was specified, set the volume label to
Temporary Storage Z
.
-
-
If the volume is ephemeral (SSD or HDD – not Amazon EBS), create an
Important.txt
file at the root of the volume with the following content:This is an 'Instance Store' disk and is provided at no additional charge. *This disk offers increased performance since it is local to the host *The number of Instance Store disks available to an instance vary by instance type *DATA ON THIS DRIVE WILL BE LOST IN CASES OF IMPAIRMENT OR STOPPING THE INSTANCE. PLEASE ENSURE THAT ANY IMPORTANT DATA IS BACKED UP FREQUENTLY For more information, please refer to: Instance store temporary block storage for Amazon EC2 instances.
-
Set the drive letter to the value specified in the
letter
input parameter.
Stages: You can run the initializeVolume
task during the PostReady
and UserData
stages.
Frequency: always.
- Inputs
-
You can configure runtime parameters as follows:
- devices (list of maps)
-
(Conditional) Configuration for each device that the launch agent initializes. This is required if the
initialize
input parameter is set todevices
.-
device (string, required) – Identifies the device during instance creation. For example,
xvdb
,xvdf
, or\dev\nvme0n1
. -
letter (string, optional) – One character. The drive letter to assign.
-
name (string, optional) – The volume name to assign.
-
partition (string, optional) – Specify one of the following values for the type of partition to create, or let the launch agent default based on volume size:
-
mbr
-
gpt
-
-
- initialize (string)
-
(Required) Specify exactly one of the following values:
-
all
-
devices
-
- Examples
-
The following examples show sample input configurations for the
initializeVolume
task.Example 1: Initialize two volumes on an instance
This example shows an
initializeVolume
task that initializes two secondary volumes on an instance. The device namedDataVolume2
in the example is ephemeral.task: initializeVolume inputs: initialize: devices devices: - device: xvdb name: DataVolume1 letter: D partition: mbr - device: /dev/nvme0n1 name: DataVolume2 letter: E partition: gpt
Example 2: Initialize EBS volumes attached to an instance
This example shows an initializeVolume
task
that initializes all empty EBS volumes that are attached to
the instance.
task: initializeVolume inputs: initialize: all
optimizeEna
Optimizes ENA settings based on the current instance type; might reboot the instance.
Frequency — always
AllowedStages — [PostReady, UserData]
Inputs — none
Example
task: optimizeEna
setAdminAccount
Sets attributes for the default administrator account that is created on the local machine.
Frequency — once
AllowedStages — [PreReady]
Inputs —
name
: (string) name of the administrator account
password
: (map)
type
: (string) strategy to set the password, either as
static
, random
, or doNothing
data
: (string) stores data if the type
field is
static
Example
task: setAdminAccount inputs: name: Administrator password: type: random
setDnsSuffix
Adds DNS suffixes to the list of search suffixes. Only suffixes that do not already exist are added to the list. For more information about how launch agents set DNS suffixes, see Configure DNS Suffix for EC2 Windows launch agents.
Frequency — always
AllowedStages — [PreReady]
Inputs —
suffixes
: (list of strings) list of one or more valid DNS
suffixes; valid substitution variables are $REGION
and
$AZ
Example
task: setDnsSuffix inputs: suffixes: - $REGION.ec2-utilities.amazonaws.com
setHostName
Sets the hostname of the computer to a custom string or, if
hostName
is not specified, the private IPv4 address.
Frequency — always
AllowedStages — [PostReady, UserData]
Inputs —
hostName
: (string) optional host name, which must be formatted as
follows.
-
Must be 15 characters or less
-
Must contain only alphanumeric (a-z, A-Z, 0-9) and hyphen (-) characters.
-
Must not consist entirely of numerical characters.
reboot
: (boolean) denotes whether a reboot is permitted when the
hostname is changed
Example
task: setHostName inputs: reboot: true
setWallpaper
Creates the setwallpaper.lnk
shortcut file in the startup folder
of each existing user except for Default User
. This shortcut file
runs when the user logs in for the first time after instance boot. It sets up
the instance with a custom wallpaper that displays the instance attributes.
The shortcut file path is:
$env:SystemDrive/Users/<user>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs/Startup/setwallpaper.lnk
Note
When you remove the setWallpaper
task, it does not delete this
shortcut file. For more information, see setWallpaper task is not enabled but the wallpaper resets
at reboot.
Stages: You can configure wallpaper during the
PreReady
and UserData
stages.
Frequency: always
Wallpaper configuration
You can use the following settings to configure your wallpaper.
- Inputs
-
Input parameters that you provide, and attributes that you can set to configure your wallpaper:
- attributes (list of strings)
-
(Optional) You can add one or more of the following attributes to your wallpaper:
-
architecture
-
availabilityZone
-
hostName
-
instanceId
-
instanceSize
-
memory
-
network
-
privateIpAddress
-
publicIpAddress
-
- instanceTags
-
(Optional) You can use exactly one of the following options for this setting.
-
AllTags (string) – Add all instance tags to your wallpaper.
instanceTags: AllTags
-
instanceTags (list of strings) – Specify a list of instance tag names to add to your wallpaper. For example:
instanceTags: - Tag 1 - Tag 2
-
- path (string)
-
(Required) The filename path of the local .jpg format image file to use for your wallpaper image.
Example
The following example shows wallpaper configuration inputs that set the
file path for the wallpaper background image, along with instance tags named
Tag 1
and Tag 2
, and attributes that
include the host name, instance ID, and private and public IP addresses for
the instance.
task: setWallpaper inputs: path: C:\ProgramData\Amazon\EC2Launch\wallpaper\Ec2Wallpaper.jpg attributes: - hostName - instanceId - privateIpAddress - publicIpAddress instanceTags: - Tag 1 - Tag 2
Note
You must enable tags in metadata to show tags on the wallpaper. For more information about instance tags and metadata, see View tags for your EC2 instances using instance metadata.
startSsm
Starts the Systems Manager (SSM) service following Sysprep.
Frequency — always
AllowedStages — [PostReady, UserData]
Inputs — none
Example
task: startSsm
sysprep
Resets the service state, updates unattend.xml
, disables RDP, and
runs Sysprep. This task runs only after all other tasks are completed.
Frequency — once
AllowedStages — [UserData]
Inputs —
clean
: (boolean) cleans instance logs before running
Sysprep
shutdown
: (boolean) shuts down the instance after running
Sysprep
Example
task: sysprep inputs: clean: true shutdown: true
writeFile
Writes a file to a destination.
Frequency — see Inputs
AllowedStages — [PostReady, UserData]
Inputs —
frequency
: (string) one of once
or
always
destination
: (string) path to which to write the content
content
: (string) text to write to the destination
Example
task: writeFile inputs: - frequency: once destination: C:\Users\Administrator\Desktop\booted.txt content: Windows Has Booted