Summary: Late 2015, AWS introduced a new feature called SSM (Simple System Manager) which lets you remotely execute commands on Windows (and Linux) server instances within AWS EC2. Unlike Windows Remote Management, SSM leverages the EC2 infrastructure to directly interact with the server instance, bypassing the need for WinRM ports to be opened up. In addition, SSM commands are interacting with the EC2Config service running on the server instance.
SSM supports several methods on the remote instance including running PowerShell commands as well as a very powerful Windows Update method (which also manages rebooting the server instance). Here’s a list of the available Windows methods in SSM:
- AWS-JoinDirectoryServiceDomain: join an AWS Directory
- AWS-RunPowerShellScript: run PowerShell commands or scripts
- AWS-UpdateEC2Config: update the EC2Config service
- AWS-ConfigureWindowsUpdate: configure Windows Update settings
- AWS-InstallApplication: install, repair, or uninstall software using an MSI package
- AWS-InstallPowerShellModule: install PowerShell modules
- AWS-ConfigureCloudWatch: configure Amazon CloudWatch Logs to monitor applications and systems
- AWS-ListWindowsInventory: collect information about an EC2 instance running in Windows
- AWS-FindWindowsUpdates: scan an instance and determines which updates are missing
- AWS-InstallMissingWindowsUpdates: install missing updates on your EC2 instance
- AWS-InstallSpecificWindowsUpdates: install one or more specific updates
Note: SSM commands are run from the Local System account on the EC2 server instance, meaning they are run as Administrator.
The following examples show how to leverage SSM via the AWS CLI utility. AWS CLI must first be installed and configured with the proper credentials for these examples to work. These commands can be run from either a CMD or PowerShell prompt.
Example 1 – Run a PowerShell command with SSM: This demonstrates using PowerShell to modify a firewall rule using SSM on an EC2 instance. Where using User-Data can be used to run PowerShell commands when EC2 creates instances, SSM can be run anytime after the instance is running.
aws ssm send-command --instance-ids "i-12345d8d" --document-name "AWS-RunPowerShellScript" --comment "Update Firewall Rule" --parameters commands="Set-NetFirewallRule -Name WINRM-HTTP-In-TCP-PUBLIC -RemoteAddress Any"
Example 2 – Install all missing updates: This is a very powerful method in SSM where all missing updates can be applied to an EC2 instance with a single command. This method also manages rebooting the instance after the updates are installed, if necessary.
aws ssm send-command --instance-ids "i-12345a86" --document-name "AWS-InstallMissingWindowsUpdates" --comment "Install Windows Upates" --parameters UpdateLevel="All"
Note: All SSM PowerShell commands that are run on an instance are saved in ‘C:\programdata\Amazon\Ec2Config\Downloads\aws_psModule’. This can be useful for troubleshooting commands or should be considered if sensitive information is used within SSM PowerShell commands.
Once an SSM command is executed, the job details are passed back in JSON to allow for monitoring the job state. This allows for automation to query the job status and apply logic for further action.
For example, the job details can be assigned to a PowerShell variable as follows (PowerShell v.4+ is required when using the ConvertFrom-Json cmdlet):
$ssmJob = (aws ssm send-command --instance-ids "i-12345d8d" --document-name "AWS-RunPowerShellScript" --comment "Update Firewall Rule" --parameters commands="Set-NetFirewallRule -Name WINRM-HTTP-In-TCP-PUBLIC -RemoteAddress Any") | ConvertFrom-JSON
The details of the job can be viewed by inspecting the $ssmJob object as follows:
You can query for the status of an SSM job using the following example:
$ssmJobStatus = (aws ssm list-command-invocations --command-id $ssmJob.Command.CommandId) | ConvertFrom-Json $ssmJobStatus.CommandInvocations.Status