Menu
Amazon Elastic Compute Cloud
User Guide for Windows Instances

Managing Windows Instance Configuration

Amazon EC2 Systems Manager enables you to manage the configuration of your Windows instances while they are running. You create a Systems Manager document, which describes configuration tasks (for example, installing software), and then associate the document with one or more running Windows instances. The configuration agent on the instance processes the document and configures the instance as specified.

If you disassociate a Systems Manager document from an instance, this doesn't change the configuration of the instance. To change the configuration of an instance after you disassociate an document, you must create a new document that describes the configuration tasks (for example, uninstalling software), and then associate it with the instance.

To run scripts at instance launch only, consider using user data execution instead. For more information, see User Data Execution.

For more complex automation scenarios, consider using AWS CloudFormation or AWS OpsWorks instead. For more information, see the AWS CloudFormation User Guide or the AWS OpsWorks User Guide.

Prerequisites

  • The EC2Config service processes Systems Manager documents and configures the instance as specified. Download and install the latest version of the EC2Config service to each server to configure. For more information, see Installing the Latest Version of EC2Config.

  • SSM Config and Run Command have the same limitations, prerequisites, and IAM permission requirements. Prepare your environment as described in Setting Up Systems Manager in the Amazon EC2 Systems Manager User Guide.

Limitations

  • SSM Config is supported only for Windows instances.

  • SSM Config is available in the following regions.

Grant IAM Users Access to SSM Config

Systems Manager documents run with administrative privilege on Windows instances because the EC2Config service runs in the Local System account. If a user has permission to execute any of the pre-defined Systems Manager documents, then that user also has administrator access to the instance. Delegate access to SSM Config and EC2 Run Command judiciously. This becomes extremely important if you create your own Systems Manager documents. Amazon Web Services does not provide guidance about how to create secure Systems Manager documents. You create Systems Manager documents and delegate access to Run Command actions at your own risk. As a security best practice, we recommend that you create low-level Systems Manager documents for low security tasks and delegate access to non-administrators.

Create the JSON File

Open a text editor, add the JSON content for the Systems Manager document, and then save the file with a .json file extension.

For more information about the structure of the JSON for a Systems Manager document, see Systems Manager Documents in the Amazon EC2 Systems Manager User Guide.

Example: Install Applications

The following JSON describes applications to install on the instance. For each application, use source to specify the URL of its .msi file.

Copy
{ "schemaVersion": "1.0", "description": "Example instance configuration tasks", "runtimeConfig": { "aws:applications": { "properties": [ { "action": "Install", "source": "http://dev.mysql.com/get/Downloads/MySQLInstaller/mysql-installer-community-5.6.22.0.msi" }, { "action": "Install", "source": "https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi" }, { "action": "Install", "source": "http://download.winzip.com/winzip190-64.msi", "parameters": "INSTALLDIR=\"C:\\Program Files\\WinZipXX\"" } ] } } }

Example: Install PowerShell Modules and Run Commands

The following JSON describes PowerShell modules to install on your instance. For each module, source specifies the URL of the module and runCommand specifies the PowerShell command to run.

Copy
{ "schemaVersion": "1.0", "description": "Example instance configuration tasks", "runtimeConfig": { "aws:psModule": { "properties": [ { "description": "Example to install windows update PS module and install all .NET 4 updates.", "source": "https://gallery.technet.microsoft.com/scriptcenter/2d191bcd-3308-4edd-9de2-88dff796b0bc/file/41459/43/PSWindowsUpdate.zip", "runCommand": "Get-WUInstall -ServiceID 9482f4b4-e343-43b6-b170-9a65bc822c77 -Title \".NET Framework 4\" -AcceptAll" }, { "description": "Example to install chocolatey package provider and use it to install 7zip and GoogleChrome.", "runCommand": [ "$url = 'https://chocolatey.org/install.ps1'" , "iex ((new-object net.webclient).DownloadString($url))", "choco install -y 7zip", "choco install -y GoogleChrome" ] } ] } } }

Example: Join an AWS Domain

For information about using SSM Config to join a Windows instance to a directory, see Joining a Windows Instance to an AWS Directory Service Domain.

Example: Send Data to Amazon CloudWatch

For information about using SSM Config to send data to Amazon CloudWatch, see Use Systems Manager State Manager.

Create a Systems Manager Document

To create a document, specify the JSON file that you created.

Tools for Windows PowerShell

Use the following New-SSMDocument command to name the document and make it available for use.

Copy
PS C:\> $contents = Get-Content -Raw my-custom-config.json | Out-String PS C:\> New-SSMDocument -Content $contents -Name "my-custom-config" -DocumentType "Command"

AWS CLI

Use the following create-document command to name the document and make it available for use.

Copy
aws ssm create-document --content file://my-custom-config.json --name "my-custom-config"

Associate a Systems Manager Document with an Instance

Associate the document that you created with a Windows instance. An instance can be associated with one document at a time. If you associate a document with an instance that already has an associated document, the new document replaces the existing document.

Tools for Windows PowerShell

Use the following New-SSMAssociation command to associate your document with your Windows instance.

Copy
PS C:\> New-SSMAssociation -InstanceId i-1a2b3c4d -Name "my-custom-config"

AWS CLI

Use the following create-association command to associate your document with your Windows instance.

Copy
aws ssm create-association --instance-id i-1a2b3c4d --name "my-custom-config"

Manually Apply the Configuration

If you need to ensure that your instance is configured as specified in its associated Systems Manager document, you can run the ec2config-cli tool on your instance as follows:

Copy
ec2config-cli --apply-configuration

Note that you can use Windows Task Scheduler to run ec2config-cli periodically to ensure that your instance maintains its configuration.

You can verify that ec2config-cli is installed by checking for it in the C:\Program Files\Amazon\Ec2ConfigService directory. If you do not have ec2config-cli, you can get it by installing the current version of the EC2Config service. For more information, see Installing the Latest Version of EC2Config.

Disassociate a Systems Manager Document from an Instance

You can't update a Systems Manager document after you create it. To associate a different document with your instance, you can delete the existing association and then associate a new document with the instance. Note that terminating an instance does not automatically disassociate an associated document.

Tools for Windows PowerShell

Use the following Remove-SSMAssociation command to disassociate a document from your Windows instance.

Copy
PS C:\> Remove-SSMAssociation -InstanceId i-1a2b3c4d -Name "my-custom-config"

AWS CLI

Use the following delete-association command to disassociate a document from your Windows instance.

Copy
aws ssm delete-association --instance-id i-1a2b3c4d --name "my-custom-config"

Delete a Systems Manager Document

When you are finished with a Systems Manager document, you can delete it. You must disassociate a document from any instances it is associated with before you can delete it.

Tools for Windows PowerShell

Use the following Remove-SSMDocument command to delete your document.

Copy
PS C:\> Remove-SSMDocument -Name "my-custom-config"

AWS CLI

Use the following delete-document command to delete your document.

Copy
aws ssm delete-document --name "my-custom-config"

Troubleshooting

The following information can help you troubleshoot problems with SSM Config.

Log4net Logging

The EC2Config service logs information in the following files using Apache log4net. The information in these files can help you troubleshoot problems.

  • C:\Windows\System32\winevt\Logs\EC2ConfigService.evtx

  • C:\Program Files\Amazon\Ec2ConfigService\Logs

  • LocalSystem %LOCALAPPDATA%

    • Windows Server 2008 or Windows Server 2012

      C:\Windows\System32\config\systemprofile\AppData\Local\Amazon\Ec2Config\Logs\Ec2ConfigPluginFramework.txt

    • Windows Server 2003

      C:\Documents and Settings\Default User\Local Settings\Amazon\Ec2Config\InstanceData\Logs\Ec2ConfigPluginFramework.txt

You can enable extended logging by updating the log4net.config file. By default, the configuration file is located in the C:\Program Files\Amazon\Ec2ConfigService\ directory.

For more information, see Apache log4net Manual - Configuration. For examples of log4net configurations, see Apache log4net Config Examples.

Windows Event Logs

The EC2Config service also logs information in a Windows Event log named Ec2ConfigService.

You can extract information from this event log to a log file by executing the following command from an elevated PowerShell command prompt:

Copy
PS C:\> Get-EventLog Ec2ConfigService | Sort-Object Index | Format-Table Message -AutoSize -Wrap | Out-File -Width 240 "C:\Program Files\Amazon\Ec2ConfigService\Logs\PluginFramework.txt"

If you want to log Windows Events to a log file with debugging enabled you must update the log4net.config file root element as follows:

<root> 
    <level value="DEBUG"/>
    <appender-ref ref="RollingFileAppender"/> 
    <appender-ref ref="EventLogAppender"/> 
</root>

EC2 Console System Log

The following output in the EC2 console system log indicates that the EC2Config service was unable to connect to an SSM Config endpoint. These issues indicate problems with authorization and IAM role permissions, as noted in the following output messages:

Info: EC2Config configuration status:3;region:us-east-1;iam:0;authz:0 The output can
help you troubleshoot the cause of the failure: configuration status:3: The calls to SSM
failed. Ensure that you have granted the required IAM permissions to IAM users. SSM also
requires an Internet connection from your instance.
iam:0: The instance was not launched with an IAM role. You cannot download documents
if there is no IAM role/credentials associated with the instance.
authz:0: The instance is not authorized to access SSM. This happens if you launched
the instance without an IAM role, or if the role associated with your instance does not
have the necessary permissions to access the service.

You can troubleshoot specific reasons for document execution failure by checking the status of the association using the describe-association (AWS CLI) command or the Get-SSMAssociation (Tools for Windows PowerShell) command.