Walkthrough: Use the Amazon Tools for Windows PowerShell with Run Command
The following examples show how to use the Amazon Tools for Windows PowerShell to view information about commands and command parameters, how to run commands, and how to view the status of those commands. This walkthrough includes an example for each of the pre-defined Amazon Systems Manager documents.
Important
Only trusted administrators should be allowed to use Systems Manager pre-configured documents shown in this topic. The commands or scripts specified in Systems Manager documents run with administrative permission on your managed nodes. If a user has permission to run any of the predefined Systems Manager documents (any document that begins with Amazon), then that user also has administrator access to the node. For all other users, you should create restrictive documents and share them with specific users.
Topics
- Configure Amazon Tools for Windows PowerShell session settings
- List all available documents
- Run PowerShell commands or scripts
- Install an application using the AWS-InstallApplication document
- Install a PowerShell module using the AWS-InstallPowerShellModule JSON document
- Join a managed node to a Domain using the AWS-JoinDirectoryServiceDomain JSON document
- Send Windows metrics to Amazon CloudWatch Logs using the AWS-ConfigureCloudWatch document
- Update EC2Config using the AWS-UpdateEC2Config document
- Turn on or turn off Windows automatic update using the AWS-ConfigureWindowsUpdate document
- Manage Windows updates using Run Command
Configure Amazon Tools for Windows PowerShell session settings
Specify your credentials
Open Tools for Windows PowerShell on your local computer and run the following command to specify your credentials. You must either have administrator permissions on the managed nodes you want to configure or you must have been granted the appropriate permission in Amazon Identity and Access Management (IAM). For more information, see Setting up managed nodes for Amazon Systems Manager.
Set-AWSCredentials –AccessKey
key-name
–SecretKeykey-name
Set a default Amazon Web Services Region
Run the following command to set the region for your PowerShell session. The example uses the US East (Ohio) Region (us-east-2). Run Command is available in the Amazon Web Services Regions listed in Systems Manager service endpoints in the Amazon Web Services General Reference.
Set-DefaultAWSRegion ` -Region us-east-2
List all available documents
This command lists all documents available for your account.
Get-SSMDocumentList
Run PowerShell commands or scripts
Using Run Command and the AWS-RunPowerShell
document, you can run
any command or script on a managed node as if you were logged on locally. You
can issue commands or enter a path to a local script to run the command.
Note
For information about rebooting managed nodes when using Run Command to call scripts, see Handling reboots when running commands.
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-RunPowerShellScript"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-RunPowerShellScript" | Select -ExpandProperty Parameters
Send a command using the AWS-RunPowerShellScript
document
The following command shows the contents of the "C:\Users"
directory and the contents of the "C:\"
directory on two
managed nodes.
$runPSCommand = Send-SSMCommand ` -InstanceIds @("
instance-ID-1
", "instance-ID-2
") ` -DocumentName "AWS-RunPowerShellScript" ` -Comment "Demo AWS-RunPowerShellScript with two instances" ` -Parameter @{'commands'=@('dir C:\Users', 'dir C:\')}
Get command request details
The following command uses the CommandId
to get the
status of the command execution on both managed nodes. This example uses
the CommandId
that was returned in the previous command.
Get-SSMCommand ` -CommandId $runPSCommand.CommandId
The status of the command in this example can be Success, Pending, or InProgress.
Get command information per managed node
The following command uses the CommandId
from the
previous command to get the status of the command execution on a per
managed node basis.
Get-SSMCommandInvocation ` -CommandId $runPSCommand.CommandId
Get command information with response data for a specific managed node
The following command returns the output of the original
Send-SSMCommand
for a specific managed node.
Get-SSMCommandInvocation ` -CommandId $runPSCommand.CommandId ` -Details $true ` -InstanceId
instance-ID
| Select -ExpandProperty CommandPlugins
Cancel a command
The following command cancels the Send-SSMCommand
for the
AWS-RunPowerShellScript
document.
$cancelCommand = Send-SSMCommand ` -InstanceIds @("
instance-ID-1
","instance-ID-2
") ` -DocumentName "AWS-RunPowerShellScript" ` -Comment "Demo AWS-RunPowerShellScript with two instances" ` -Parameter @{'commands'='Start-Sleep –Seconds 120; dir C:\'} Stop-SSMCommand -CommandId $cancelCommand.CommandId
Check the command status
The following command checks the status of the Cancel
command.
Get-SSMCommand ` -CommandId $cancelCommand.CommandId
Install an
application using the AWS-InstallApplication
document
Using Run Command and the AWS-InstallApplication
document, you can
install, repair, or uninstall applications on managed nodes. The command
requires the path or address to an MSI.
Note
For information about rebooting managed nodes when using Run Command to call scripts, see Handling reboots when running commands.
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-InstallApplication"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-InstallApplication" | Select -ExpandProperty Parameters
Send a command using the AWS-InstallApplication
document
The following command installs a version of Python on your managed node in
unattended mode, and logs the output to a local text file on your
C:
drive.
$installAppCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallApplication" ` -Parameter @{'source'='https://www.python.org/ftp/python/2.7.9/python-2.7.9.msi'; 'parameters'='/norestart /quiet /log c:\pythoninstall.txt'}
Get command information per managed node
The following command uses the CommandId
to get the
status of the command execution.
Get-SSMCommandInvocation ` -CommandId $installAppCommand.CommandId ` -Details $true
Get command information with response data for a specific managed node
The following command returns the results of the Python installation.
Get-SSMCommandInvocation ` -CommandId $installAppCommand.CommandId ` -Details $true ` -InstanceId
instance-ID
| Select -ExpandProperty CommandPlugins
Install a PowerShell
module using the AWS-InstallPowerShellModule
JSON
document
You can use Run Command to install PowerShell modules on managed nodes. For more
information about PowerShell modules, see Windows PowerShell Modules
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-InstallPowerShellModule"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-InstallPowerShellModule" | Select -ExpandProperty Parameters
Install a PowerShell module
The following command downloads the EZOut.zip file, installs it, and then runs an additional command to install XPS viewer. Lastly, the output of this command is uploaded to an S3 bucket named "amzn-s3-demo-bucket".
$installPSCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallPowerShellModule" ` -Parameter @{'source'='https://gallery.technet.microsoft.com/EZOut-33ae0fb7/file/110351/1/EZOut.zip';'commands'=@('Add-WindowsFeature -name XPS-Viewer -restart')} ` -OutputS3BucketNameamzn-s3-demo-bucket
Get command information per managed node
The following command uses the CommandId
to get the
status of the command execution.
Get-SSMCommandInvocation ` -CommandId $installPSCommand.CommandId ` -Details $true
Get command information with response data for the managed node
The following command returns the output of the original
Send-SSMCommand
for the specific
CommandId
.
Get-SSMCommandInvocation ` -CommandId $installPSCommand.CommandId ` -Details $true | Select -ExpandProperty CommandPlugins
Join a managed node to a
Domain using the AWS-JoinDirectoryServiceDomain
JSON
document
Using Run Command, you can quickly join a managed node to an Amazon Directory Service domain. Before executing this command, create a directory. We also recommend that you learn more about the Amazon Directory Service. For more information, see the Amazon Directory Service Administration Guide.
You can only join a managed node to a domain. You can't remove a node from a domain.
Note
For information about managed nodes when using Run Command to call scripts, see Handling reboots when running commands.
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-JoinDirectoryServiceDomain"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-JoinDirectoryServiceDomain" | Select -ExpandProperty Parameters
Join a managed node to a domain
The following command joins a managed node to the given Amazon Directory Service domain and uploads any generated output to the example Amazon Simple Storage Service (Amazon S3) bucket.
$domainJoinCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-JoinDirectoryServiceDomain" ` -Parameter @{'directoryId'='d-example01
'; 'directoryName'='ssm.example.com
'; 'dnsIpAddresses'=@('192.168.10.195
', '192.168.20.97
')} ` -OutputS3BucketNameamzn-s3-demo-bucket
Get command information per managed node
The following command uses the CommandId
to get the
status of the command execution.
Get-SSMCommandInvocation ` -CommandId $domainJoinCommand.CommandId ` -Details $true
Get command information with response data for the managed node
This command returns the output of the original
Send-SSMCommand
for the specific
CommandId
.
Get-SSMCommandInvocation ` -CommandId $domainJoinCommand.CommandId ` -Details $true | Select -ExpandProperty CommandPlugins
Send Windows metrics to
Amazon CloudWatch Logs using the AWS-ConfigureCloudWatch
document
You can send Windows Server messages in the application, system, security, and Event Tracing for Windows (ETW) logs to Amazon CloudWatch Logs. When you allow logging for the first time, Systems Manager sends all logs generated within one (1) minute from the time that you start uploading logs for the application, system, security, and ETW logs. Logs that occurred before this time aren't included. If you turn off logging and then later turn logging back on, Systems Manager sends logs from the time it left off. For any custom log files and Internet Information Services (IIS) logs, Systems Manager reads the log files from the beginning. In addition, Systems Manager can also send performance counter data to CloudWatch Logs.
If you previously turned on CloudWatch integration in EC2Config, the Systems Manager settings
override any settings stored locally on the managed node in the
C:\Program
Files\Amazon\EC2ConfigService\Settings\AWS.EC2.Windows.CloudWatch.json
file. For more information about using EC2Config to manage performance counters
and logs on a single managed node, see Collecting metrics and logs from Amazon EC2 instances and on-premises servers
with the CloudWatch agent in the Amazon CloudWatch User Guide.
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-ConfigureCloudWatch"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-ConfigureCloudWatch" | Select -ExpandProperty Parameters
Send application logs to CloudWatch
The following command configures the managed node and moves Windows Applications logs to CloudWatch.
$cloudWatchCommand = Send-SSMCommand ` -InstanceID
instance-ID
` -DocumentName "AWS-ConfigureCloudWatch" ` -Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"ApplicationEventLog", "FullName":"AWS.EC2.Windows.CloudWatch.EventLog.EventLogInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"LogName":"Application", "Levels":"7"}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatchLogsOutput,AWS.EC2.Windows.CloudWatch", "Parameters":{"Region":"region
", "LogGroup":"my-log-group
", "LogStream":"instance-id
"}}], "Flows":{"Flows":["ApplicationEventLog,CloudWatch"]}}}'}
Get command information per managed node
The following command uses the CommandId
to get the
status of the command execution.
Get-SSMCommandInvocation ` -CommandId $cloudWatchCommand.CommandId ` -Details $true
Get command information with response data for a specific managed node
The following command returns the results of the Amazon CloudWatch configuration.
Get-SSMCommandInvocation ` -CommandId $cloudWatchCommand.CommandId ` -Details $true ` -InstanceId
instance-ID
| Select -ExpandProperty CommandPlugins
Send performance counters to CloudWatch using the
AWS-ConfigureCloudWatch
document
The following demonstration command uploads performance counters to CloudWatch. For more information, see the Amazon CloudWatch User Guide.
$cloudWatchMetricsCommand = Send-SSMCommand ` -InstanceID
instance-ID
` -DocumentName "AWS-ConfigureCloudWatch" ` -Parameter @{'properties'='{"engineConfiguration": {"PollInterval":"00:00:15", "Components":[{"Id":"PerformanceCounter", "FullName":"AWS.EC2.Windows.CloudWatch.PerformanceCounterComponent.PerformanceCounterInputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"CategoryName":"Memory", "CounterName":"Available MBytes", "InstanceName":"", "MetricName":"AvailableMemory", "Unit":"Megabytes","DimensionName":"", "DimensionValue":""}},{"Id":"CloudWatch", "FullName":"AWS.EC2.Windows.CloudWatch.CloudWatch.CloudWatchOutputComponent,AWS.EC2.Windows.CloudWatch", "Parameters":{"AccessKey":"", "SecretKey":"","Region":"region
", "NameSpace":"Windows-Default"}}], "Flows":{"Flows":["PerformanceCounter,CloudWatch"]}}}'}
Update EC2Config using
the AWS-UpdateEC2Config
document
Using Run Command and the AWS-EC2ConfigUpdate
document, you can
update the EC2Config service running on your Windows Server managed nodes. This
command can update the EC2Config service to the latest version or a version you
specify.
View the description and available parameters
Get-SSMDocumentDescription ` -Name "AWS-UpdateEC2Config"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-UpdateEC2Config" | Select -ExpandProperty Parameters
Update EC2Config to the latest version
$ec2ConfigCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-UpdateEC2Config"
Get command information with response data for the managed node
This command returns the output of the specified command from the
previous Send-SSMCommand
.
Get-SSMCommandInvocation ` -CommandId $ec2ConfigCommand.CommandId ` -Details $true ` -InstanceId
instance-ID
| Select -ExpandProperty CommandPlugins
Update EC2Config to a specific version
The following command downgrades EC2Config to an older version.
Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-UpdateEC2Config" ` -Parameter @{'version'='4.9.3519'; 'allowDowngrade'='true'}
Turn on or turn
off Windows automatic update using the
AWS-ConfigureWindowsUpdate
document
Using Run Command and the AWS-ConfigureWindowsUpdate
document, you
can turn on or turn off automatic Windows updates on your Windows Server managed
nodes. This command configures the Windows Update Agent to download and install
Windows updates on the day and hour that you specify. If an update requires a
reboot, the managed node reboots automatically 15 minutes after updates have
been installed. With this command you can also configure Windows Update to check
for updates but not install them. The AWS-ConfigureWindowsUpdate
document is compatible with Windows Server 2008, 2008 R2, 2012, 2012 R2, and
2016.
View the description and available parameters
Get-SSMDocumentDescription ` –Name "AWS-ConfigureWindowsUpdate"
View more information about parameters
Get-SSMDocumentDescription ` -Name "AWS-ConfigureWindowsUpdate" | Select -ExpandProperty Parameters
Turn on Windows automatic update
The following command configures Windows Update to automatically download and install updates daily at 10:00 PM.
$configureWindowsUpdateCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-ConfigureWindowsUpdate" ` -Parameters @{'updateLevel'='InstallUpdatesAutomatically'; 'scheduledInstallDay'='Daily'; 'scheduledInstallTime'='22:00'}
View command status for allowing Windows automatic update
The following command uses the CommandId
to get the
status of the command execution for allowing Windows automatic
update.
Get-SSMCommandInvocation ` -Details $true ` -CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
Turn off Windows automatic update
The following command lowers the Windows Update notification level so the system checks for updates but doesn't automatically update the managed node.
$configureWindowsUpdateCommand = Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-ConfigureWindowsUpdate" ` -Parameters @{'updateLevel'='NeverCheckForUpdates'}
View command status for turning off Windows automatic update
The following command uses the CommandId
to get the
status of the command execution for turning off Windows automatic
update.
Get-SSMCommandInvocation ` -Details $true ` -CommandId $configureWindowsUpdateCommand.CommandId | Select -ExpandProperty CommandPlugins
Manage Windows updates using Run Command
Using Run Command and the AWS-InstallWindowsUpdates
document, you
can manage updates for Windows Server managed nodes. This command scans for or
installs missing updates on your managed nodes and optionally reboots following
installation. You can also specify the appropriate classifications and severity
levels for updates to install in your environment.
Note
For information about rebooting managed nodes when using Run Command to call scripts, see Handling reboots when running commands.
The following examples demonstrate how to perform the specified Windows Update management tasks.
Search for all missing Windows updates
Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Scan'}
Install specific Windows updates
Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Install';'IncludeKbs'='kb-ID-1
,kb-ID-2
,kb-ID-3
';'AllowReboot'='True'}
Install important missing Windows updates
Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Install';'SeverityLevels'='Important';'AllowReboot'='True'}
Install missing Windows updates with specific exclusions
Send-SSMCommand ` -InstanceId
instance-ID
` -DocumentName "AWS-InstallWindowsUpdates" ` -Parameters @{'Action'='Install';'ExcludeKbs'='kb-ID-1
,kb-ID-2
';'AllowReboot'='True'}