Using AWS SSM With Windows Instances

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:

$ssmJob.Command

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

Enjoy!

 

Advertisements

CloudStack API PowerShell Example

Summary: This script uses a simple command, sent via PowerShell and REST to a CloudStack API, in order to list all visible Virtual Machines as well as their current state (‘Running’, ‘Stopped’, etc.).

CloudStack is an Apache Open Source project for managing a cloud service (much like OpenStack, but it’s been around a LOT longer). CloudStack also has an impressive list of customers (check out their Wikipedia post above). Like most cloud services, CloudStack has an API (REST) for programmatically interacting with the service.

Note: A valid account’s API public key and secret are required for this script.

This API authenticates requests by using an account’s public key and secret to create a signature for the API request. In order the create the signature, the command being signed must be broken down into key/value pairs, sorted, reassembled for signing, then converted to lower case.

On-going problems: This script mostly works. But it (or the API) has problems with certain command strings. And PowerShell doesn’t seem to like the API’s output in JSON (so this script uses the default XML). If you find a solution, please reach out.

Datapipe’s documentation of their implementation of the CloudStack API can be found here: https://docs.cloud.datapipe.com/developers/api/developers-guide

Here is a sample list of command strings that leverage the listVirtualMachines method (your mileage may vary):

command=listVirtualMachines
command=listVirtualMachines&state=Running
command=listVirtualMachines&account=General
command=listVirtualMachines&zoneid=13
command=listVirtualMachines&groupid=21&account=General
command=listVirtualMachines&groupid=21&account=General&state=Running
command=listVirtualMachines&state=Stopped&response=json
command=listVirtualMachines&id=3a57b2d3-b95a-4892-903a-34f4662ed475&response=json
command=listVirtualMachines&id=3a57b2d3-b95a-4892-903a-34f4662ed475
command=listVirtualMachines&state=Running&response=json

Note: This script requires PowerShell v.3+ due to the use of the Invoke-RestMethod cmdlets.

openstackApiExample.ps1

#
# Name:: openstackApiExample.ps1
# Version:: 0.1.0 (6/27/2016)
# Script Description:: Queries the Datapipe Cloud (Cloud-Stack) REST API
#
# API Documentation:: https://docs.cloud.datapipe.com/developers/api/developers-guide
#
# Author(s):: Otto Helweg
#
# PowerShell v.3+ is required for the Invoke-RestMethod cmdlet
#
# Parameters: -k = apikey, -s = secret (both are required)
# Example: .\apiExample.ps1 -k "F2rrzJiluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJ" -s "iluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJiluwK39LpD6PvyF2rrzJiluwK3"

param($k,$s)

$uri=@{}
$baseUri = "https://cloud.datapipe.com/api/compute/v1?"
$command = "command=listVirtualMachines"
# The following is a command string that should work, but doesn't
# $command = "command=listVirtualMachines&state=Running"
$uri["apikey"] = $k
$secret = $s

# Build the Command String for getting an authorization signature
# First extract all key/value pairs in the command into the uri hash
$subCommand = $command.split("&")
foreach ($item in $subCommand | Sort-Object) {
  if ($item -like "*=*") {
    $items = $item.Split("=")
    $uri[$items[0]] = $items[1]
  } else {
    $uri[$item] = ""
  }
}

# Build the signing String by sorting the command key/values then make lowercase for signing
$signString = ""
foreach ($key in $uri.Keys | Sort-Object) {
  if ($uri[$key]) {
    $signString = $signString + $key + "=" + $uri[$key] + "&"
  } else {
    $signString = $signString + $key + "&"
  }
}
$signString = $signString.ToLower()
$signString = $signString.TrimEnd("&")

# Get the HMAC SHA-1 signature for the specific Command String
$hmacSha = New-Object System.Security.Cryptography.HMACSHA1
$hmacSha.key = [Text.Encoding]::ASCII.GetBytes($secret)
$signature = $hmacSha.ComputeHash([Text.Encoding]::ASCII.GetBytes($signString))
$signature = [Convert]::ToBase64String($signature)

# Build the signed REST URI
$newUri = $baseUri + $command + "&apiKey=" + $uri["apikey"] + "&signature=" + $signature
Write-Host "URI: $newUri"
Write-Host "signString: $signString"
Write-Host "Signature: $signature"

# Query for a list of all VMs
Write-Host "Querying the Cloud-Stack API..."
[xml]$vmList = Invoke-RestMethod -Method GET -Uri $newUri -ContentType "application/xml"

# List all VMs visible by the account
Write-Host ""
Write-Host "Virtual Machines:"
foreach ($vm in $vmList.listvirtualmachinesresponse.virtualmachine) {
  if ($vm.state -eq "Stopped") {
    $color = "yellow"
  } else {
    $color = "white"
  }
  Write-Host -ForegroundColor $color "$($vm.displayname) - $($vm.state)"
}

 

Enjoy!